Factor MCP

🚀 Factor MCP Server

An MCP (Model Context Protocol) server that enables AI tools to interact with Factor Protocol vaults on EVM chains.

✨ Features

• 68 MCP Tools: For complete vault management.
• Multi-chain Support: Arbitrum One, Base, Ethereum Mainnet.
• Secure Wallet Management: Foundry Keystore (Web3 V3) + AES-256-GCM encryption.
• Simulation Mode: Preview transactions before execution.
• Strategy Building: Compose DeFi strategies using building blocks.
• Foundry Integration: Fork simulation, error decoding, forge scripts.

🚀 Quick Start

One-Line Install

curl -sSL https://raw.githubusercontent.com/FactorDAO/factor-mcp/main/install.sh | bash

This will:

• Install Rust (if not present).
• Install Foundry (cast, anvil, forge).
• Clone and build Factor MCP.
• Create factor-mcp command.

Manual Installation

git clone https://github.com/FactorDAO/factor-mcp.git
cd factor-mcp
npm install
npm run build

Configuration

The server uses JSON configuration stored at ~/.factor-mcp/config.json:

{
  "alchemyApiKey": "your_api_key",
  "defaultChain": "ARBITRUM_ONE",
  "simulationMode": false,
  "logLevel": "info",
  "activeWallet": "default"
}

Environment variables can override JSON config:

• ALCHEMY_API_KEY - Alchemy API key for RPC access.
• DEFAULT_CHAIN - Default chain (ARBITRUM_ONE, OPTIMISM, BASE, SONIC, MAINNET).
• SIMULATION_MODE - Set to "true" for dry-run mode.
• LOG_LEVEL - Logging level (debug, info, warn, error).
• FACTOR_ARTIFACTS_DIR - Persist generated forge scripts to this directory (useful in Docker/ephemeral environments).

Running

# Direct execution
npm start

# Or with environment variables
ALCHEMY_API_KEY=xxx npm start

Claude Code Integration

Add to your Claude Code config (~/.config/claude-code/config.json or MCP settings):

{
  "mcpServers": {
    "factor": {
      "command": "node",
      "args": ["/path/to/factor-mcp/dist/index.js"],
      "env": {
        "ALCHEMY_API_KEY": "your_api_key"
      }
    }
  }
}

💻 Tools Reference

Configuration (5 tools)

Vault Operations (14 tools)

Vault Management (12 tools)

Lending Operations (4 tools)

Swap Operations (4 tools)

LP Operations (4 tools)

Yield Operations (1 tool)

Flash Loan (1 tool)

Token & Registry (3 tools)

Strategy Building (1 tool)

Transaction Tools (2 tools)

Profile & Strategy (6 tools)

Foundry Tools (5 tools)

🔧 Security

Wallet Storage

Wallets support two backends:

• Factor-MCP (default): ~/.factor-mcp/wallets/ — AES-256-GCM encryption, PBKDF2 key derivation (100k iterations).
• Foundry Keystore: ~/.foundry/keystores/ — Web3 Secret Storage V3 format, compatible with cast/geth.

Best Practices

1. Always use encryption for production wallets
2. Use simulation mode for testing (simulationMode: true)
3. Never commit wallet files or API keys

📦 Docker Deployment

# Build image
docker build -t factor-mcp .

# Run with docker-compose
docker-compose up -d

🛠️ Development

# Install dependencies
npm install

# Type checking
npm run typecheck

# Build
npm run build

# Run in dev mode
npm run dev

# Run tests
npm test

📚 SDK Coverage Roadmap

This roadmap tracks the MCP server's coverage of the @factordao/sdk-studio package. Items marked [x] are implemented in the MCP, items marked [ ] are SDK features not yet exposed.

Configuration & Wallet

• [x] Set active chain (ARBITRUM_ONE, BASE, MAINNET)
• [x] Set custom RPC endpoint
• [x] Get current config (chain, RPC, wallet, simulation mode)
• [x] Wallet import from private key
• [x] Wallet generation (new random)
• [x] Foundry Keystore storage (Web3 V3 format)
• [x] Factor-MCP encrypted storage (AES-256-GCM)
• [x] Use existing Foundry keystore
• [x] Get SDK address book (Pro adapter addresses)

Vault Creation & Templates

• [x] Deploy new Factor Pro vault (factor_create_vault)
• [x] Vault templates with ready-to-use params (factor_vault_templates)
• [x] Lending-ready vault templates (Aave preset)
• [x] Lending-ready vault templates (Compound V3 preset)
• [x] Lending-ready vault templates (Morpho preset)
• [x] Auto-detect accounting adapters from factory
• [x] Validate vault config before deployment (factor_validate_vault_config)
• [x] Get whitelisted factory addresses (factor_get_factory_addresses)
• [x] Immutable vault option
• [x] Configurable fees, caps, debt ratio, cooldown, upgradeability

Vault Queries

• [x] Get owned vaults (factor_get_owned_vaults)
• [x] Get vault info — assets, fees, managers, adapters (factor_get_vault_info)
• [x] Get user shares, total supply, price per share (factor_get_shares)
• [x] Get execution history with decoded calls (factor_get_executions)
• [x] Preview deposit — expected shares (factor_preview_deposit)
• [x] Preview withdrawal — expected assets (factor_preview_withdraw)
• [ ] Check if asset is valid deposit asset (isDepositAsset)
• [ ] Check if asset is valid withdraw asset (isWithdrawAsset)
• [ ] Get asset accounting adapter (getAssetAccounting)
• [ ] Get debt accounting adapter (getDebtAccounting)
• [ ] Estimate raw withdraw expected amount (estimateRawWithdrawExpectedAmount)
• [ ] USD balance breakdown via Alchemy (balanceUsd)

Vault Deposit & Withdrawal

• [x] Deposit ERC20 token (factor_deposit)
• [x] Withdraw / redeem shares (factor_withdraw)
• [ ] Deposit native token — ETH (depositNative)
• [ ] Deposit and execute strategy in one tx (depositAssetAndExecute)
• [ ] Raw withdraw with execution blocks (rawWithdraw)

Vault Fee Management

• [x] Set deposit fee (factor_set_deposit_fee)
• [x] Set withdraw fee (factor_set_withdraw_fee)
• [x] Set performance fee (factor_set_performance_fee)
• [x] Set management fee (factor_set_management_fee)
• [x] Charge performance fee (factor_charge_performance_fee)
• [x] Set fee receiver (factor_set_fee_receiver)

Vault Risk & Access Management

• [x] Set max deposit cap (factor_set_max_cap)
• [x] Set max debt ratio (factor_set_max_debt_ratio)
• [x] Set price deviation allowance (factor_set_price_deviation_allowance)
• [x] Add vault manager (factor_add_vault_manager)
• [x] Remove vault manager (factor_remove_vault_manager)
• [x] Set risk manager (factor_set_risk_manager)

Vault Strategy Configuration

• [ ] Set public strategy (setPublicStrategy)
• [ ] Remove public strategy (removePublicStrategy)
• [ ] Execute public strategy (executePublicStrategy)
• [ ] Set deposit strategy (setDepositStrategy)
• [ ] Remove deposit strategy (removeDepositStrategy)

Vault Simulation

• [ ] Simulate deposit (simulateDeposit)
• [ ] Simulate charge performance fee (simulateChargePerformanceFee)

Token & Approval

• [x] ERC20 token approval (factor_give_approval)
• [x] Get lending tokens — aTokens, debt tokens, underlying (factor_get_lending_tokens)
• [x] Add asset/debt token to vault (factor_add_vault_token)
• [ ] ERC2612 permit / gasless approval (permit adapter)

Lending — Aave V3

• [x] Supply / supply all / supply by percentage
• [x] Withdraw / withdraw all
• [x] Borrow
• [x] Repay / repay all

Lending — Compound V3

• [x] Supply / supply all
• [x] Withdraw / withdraw all
• [x] Borrow
• [x] Repay / repay all
• [ ] Claim rewards (claimRewards)

Lending — Morpho

• [x] Supply (lending)
• [x] Supply as collateral
• [x] Withdraw (lending + collateral)
• [x] Borrow
• [x] Repay / repay all

Lending — Silo V2

• [x] Supply
• [x] Withdraw
• [x] Borrow
• [x] Repay

DEX — Uniswap V3

• [x] Exact input single swap (factor_swap)
• [x] Swap all balance
• [x] Swap by percentage
• [x] Configurable fee tiers (100, 500, 3000, 10000)
• [x] Configurable slippage
• [x] Exact output single swap (factor_swap_exact_output)
• [x] Exact output single with full balance (factor_swap_exact_output with amountInMax "all")

DEX — OpenOcean

• [x] Aggregated swap (factor_swap_openocean)

DEX — Pendle PT/YT

• [x] Token to PT swap
• [x] Token to YT swap
• [x] PT to token swap
• [x] YT to token swap

DEX — Aqua

• [ ] Aqua DEX swap (Base)

LP — Uniswap V3

• [x] Create concentrated liquidity position
• [x] Add liquidity to existing position
• [x] Remove liquidity (amount or "all")
• [x] Collect accumulated fees
• [ ] Remove liquidity by percentage (removeByPercentage)

LP — Camelot V3

• [x] Create concentrated liquidity position
• [x] Add liquidity
• [x] Remove liquidity
• [x] Collect fees
• [ ] Remove liquidity by percentage (removeByPercentage)

LP — Aerodrome

• [x] Create concentrated liquidity position
• [x] Add liquidity
• [x] Remove liquidity
• [x] Collect fees

Yield — Pendle LP

• [x] Add liquidity to Pendle market
• [x] Remove liquidity
• [x] Collect fees/rewards

Flash Loans

• [x] Aave flash loan with inner strategy steps
• [x] Morpho flash loan with inner strategy steps
• [ ] Balancer flash loan (balancerFL)

Strategy Builder

• [x] Execute strategy via executeByManager
• [x] List available adapters (factor_list_adapters)
• [x] Save strategy to Stats API (factor_save_strategy)
• [x] Delete strategy from Stats API (factor_delete_strategy)
• [x] Get strategy by hash (factor_get_strategy)
• [x] Get strategies by owner (factor_get_strategies)
• [x] Save profile to Stats API (factor_save_profile)
• [x] Get profile from Stats API (factor_get_profile)
• [ ] Export strategy as calldata (export)
• [ ] Export strategy as JSON (exportToJson)
• [ ] Clone strategy (clone)
• [ ] Debug strategy step-by-step (debugFromBlocks)
• [ ] Estimate user impact (estimate / estimateFromBlocks)
• [ ] Strategy summary (summary)
• [ ] Guess token state changes (guessTokenState)

Utility Adapters

• [ ] Transfer tokens between addresses (transfer adapter)
• [ ] Refund dust amounts (refund adapter)
• [ ] Native token wrap/unwrap (native adapter)
• [ ] ERC721 / NFT operations (erc721 adapter)
• [ ] Leverage vault operations (leverageVault adapter)
• [ ] Leverage strategy building (leverageStrategy adapter)
• [ ] Deposit policy management (depositPolicy adapter)
• [ ] Gelato automation setup (gelato adapter)
• [ ] Chainlink direct price feed queries (chainlink adapter)

Adapter Discovery & Metadata

• [x] List adapters by chain (factor_list_adapters)
• [ ] Get user portfolio info across adapters (getUserInfo)
• [ ] Get markets for building block / protocol (getMarkets)
• [ ] Get markets by input token (getMarketByInToken)
• [ ] Get protocols by input token (getProtocolsByInToken)
• [ ] Get supported input tokens (getInTokens)
• [ ] Get adapter metadata (getMetadata / getMetadataByBuildingBlock)
• [ ] Get all building block types (getBuildingBlocks)

Boost System

• [ ] Add tokens to boost whitelist (addBoostTokenWhitelist)
• [ ] Remove tokens from boost whitelist (removeBoostTokenWhitelist)
• [ ] Deposit vault reward (depositRewardForVaultBN)
• [ ] Redeem boost rewards (redeemBoostRewards)
• [ ] Redeem all boost rewards (redeemBoostRewardAll)
• [ ] Get boost reward tokens (getBoostRewardTokens)
• [ ] Get earned boost tokens by user (boostEarnedTokensByUser)
• [ ] Get reward data (rewardData)
• [ ] Get reward for duration (getRewardForDuration)

Scale System

• [ ] Get Scale vaults (getVaults)
• [ ] Get Scale vault details (getVaultDetail)
• [ ] Get user Scale positions (getUserVaults)
• [ ] Get user active balance (activeBalance)
• [ ] Get total active supply (totalActiveSupply)
• [ ] Get Scale reward tokens (getScaleRewardTokens)
• [ ] Redeem Scale rewards (redeemScaleRewards)
• [ ] Redeem boost + Scale rewards combined (redeemBoostAndScaleRewards)
• [ ] Vote on gauge (vote)
• [ ] Remove vote (unvote)
• [ ] Get user / vault votes
• [ ] Claim Scale rewards (claimRewards)
• [ ] Get Scale market data (getMarketData)
• [ ] Get historical data (getHistoricalData)

Bribe System

• [ ] Create bribe (addBribe)
• [ ] Claim bribe (claimBribe)
• [ ] Get bribe info (getBribe)
• [ ] Get all bribes (getAllBribes)

Transaction & Debugging

• [x] Preview transaction with gas estimate (factor_preview_transaction)
• [x] Check transaction status (factor_get_transaction_status)
• [x] Check Foundry installation (factor_check_foundry)
• [x] Read-only contract calls via cast (factor_cast_call)
• [x] Simulate on forked network via anvil (factor_simulate_transaction)
• [x] Decode contract errors (factor_decode_error)
• [x] Run Solidity forge scripts (factor_run_forge_script)
• [x] Balance overrides for simulation
• [x] Simulation hints with auto-generated Forge scripts

Pro Adapter Availability

Only _pro adapters are used by the MCP server. Adapters without any deployment are excluded from the roadmap.

Lending

DEX

LP

Yield

Flash Loans

Accounting

Infrastructure

Note: Ethereum Mainnet has no pro adapters deployed (only factory + Chainlink accounting in testing).

Coverage Summary

📄 License

MIT