Aptos MCP

Aptos MCP is a comprehensive Model Context Protocol (MCP) server implementation for the Aptos blockchain, compatible with MCP clients like Claude Desktop or Cursor.ai. It provides a complete DeFi toolkit covering major Aptos protocols including pool discovery, lending, DEX operations, perpetual trading, liquid staking, and cross-protocol portfolio management.

Features

• 41+ MCP tools covering the complete Aptos DeFi ecosystem
• Universal Pool Discovery - Discover and list pools across all protocols
• Complete DEX integration - Liquidswap with swapping, liquidity management, and pool creation
• Professional lending protocols - Joule Finance and Echelon Finance with full lending/borrowing workflow
• Perpetual trading - MerkleTrade integration for advanced trading strategies
• DEX aggregation - Panora Exchange for optimal swap routing
• Liquid staking options - Thala Finance integrations
• Cross-protocol pool discovery - Unified pool listing across all protocols
• Stablecoin operations - MOD minting and redemption through Thala
• Native APT staking with validator insights from AI

Using with Claude Desktop

1. Install Claude Desktop if you haven't already
2. Open Claude Desktop settings
3. Add the Aptos MCP client to your configuration:

{
  "mcpServers": {
    "aptos-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@tamago-labs/aptos-mcp",
        "--aptos_private_key=YOUR_PRIVATE_KEY", 
        "--aptos_network=mainnet"
      ],
      "disabled": false
    }
  }
}

This Private Key mode is recommended for advanced users who can securely manage their private keys. The MCP client handles transactions locally without exposing any data to external servers.

Use Cases

1. Complete DeFi Portfolio Management

The agent connects to price oracles and major DeFi protocols to help you:

• Discover and monitor all available pools across DeFi protocols
• Execute complex DeFi strategies across lending, borrowing, and liquidity provision
• Trade perpetuals with advanced position management on MerkleTrade
• Optimize swap routes using Panora DEX aggregator for best rates
• Manage liquid staking positions with Thala protocols
• Track cross-protocol positions with unified portfolio analysis
• Trade and provide liquidity on Liquidswap DEX with advanced pool management
• Track lending positions across Joule Finance and Echelon Finance

2. Advanced DeFi Protocol Management

The agent assists DeFi protocol managers and power users with:

• Universal pool discovery across all Aptos DeFi protocols
• Multi-protocol position management across lending platforms
• Perpetual trading strategies with MerkleTrade integration
• Liquidity optimization strategies across different DEX pools
• Cross-protocol yield farming and reward optimization
• Risk management through diversified staking and lending
• Real-time rate comparison across lending protocols

Available Tools

Core Wallet Operations (8 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | aptos_get_address | Retrieve your wallet address | "What's my wallet address?" | | aptos_get_balance | Get APT or token balance | "Show my APT balance" | | aptos_transfer_token | Transfer tokens to another address | "Transfer 10 APT to 0x123..." | | aptos_create_token | Create a new token on Aptos | "Create a token named MyToken with symbol MTK" | | aptos_mint_token | Mint tokens to an address | "Mint 1000 MTK tokens to 0x456..." | | aptos_burn_token | Burn tokens from your account | "Burn 100 MTK tokens" | | aptos_get_token_price | Get token price | "What's the current price of APT?" | | aptos_get_transaction | Get transaction details | "Show transaction 0xabc..." |

Pool Discovery & Liquidity Management (3 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | list_liquidswap_pools | List all Liquidswap DEX pools | "Show all trading pools" | | get_liquidswap_pool_info | Get specific pool information | "Show APT/USDC pool details" | | list_thala_pools | List all Thala pools (DEX & staking) | "Show Thala pool options" |

Liquidswap DEX Operations (4 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | aptos_swap_tokens | Swap tokens via Liquidswap | "Swap 10 APT for USDC" | | aptos_add_liquidity | Add liquidity to earn fees | "Add 100 APT and 500 USDC to the pool" | | aptos_remove_liquidity | Remove liquidity from pools | "Remove 50 LP tokens from APT/USDC pool" | | aptos_create_pool | Create new trading pools | "Create a new pool for APT/USDT trading" |

Joule Finance - Complete Lending Protocol (8 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | aptos_joule_lend | Lend tokens to earn interest | "Lend 100 APT to Joule Finance" | | aptos_joule_borrow | Borrow tokens against collateral | "Borrow 50 USDC using my APT collateral" | | aptos_joule_repay | Repay borrowed tokens | "Repay 25 USDC to my lending position" | | aptos_joule_withdraw | Withdraw lent tokens | "Withdraw 50 APT from my lending position" | | aptos_joule_get_position | Get specific position details | "Show details for position pos_123" | | aptos_joule_get_all_positions | Get all lending positions | "Show all my Joule Finance positions" | | aptos_joule_claim_reward | Claim lending rewards | "Claim rewards from my lending positions" | | aptos_joule_list_pools | List all Joule lending pools | "Show available lending markets" |

Echelon Finance - Lending Protocol (6 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | list_echelon_markets | List all markets with APY data | "Show all Echelon lending markets" | | supply_to_echelon | Supply tokens to earn interest | "Supply 200 USDC to Echelon Finance" | | borrow_from_echelon | Borrow tokens against collateral | "Borrow 100 APT using USDC collateral" | | repay_to_echelon | Repay borrowed tokens | "Repay 50 APT to Echelon Finance" | | withdraw_from_echelon | Withdraw supplied tokens | "Withdraw 100 USDC from Echelon" | | get_echelon_user_position | Get user position details | "Show my position in Echelon APT market" |

MerkleTrade - Perpetual Trading (4 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | place_merkle_market_order | Place market order for perps | "Long 1000 USDC worth of APT-PERP" | | place_merkle_limit_order | Place limit order for perps | "Set limit buy for APT-PERP at $8.50" | | close_merkle_position | Close trading position | "Close my APT-PERP position" | | get_merkle_positions | Get all trading positions | "Show my perpetual positions" |

Panora - DEX Aggregator (2 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | swap_with_panora | Swap with best rates across DEXes | "Swap 100 APT for USDC using Panora" | | get_panora_quote | Get swap quote from aggregator | "Quote 50 USDC to APT via Panora" |

Thala Finance - Liquid Staking & Stablecoin (4 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | aptos_thala_stake | Stake APT for thAPT (liquid staking) | "Stake 200 APT with Thala for thAPT" | | aptos_thala_unstake | Unstake thAPT back to APT | "Unstake 100 thAPT tokens" | | aptos_thala_mint_mod | Mint MOD stablecoin | "Mint 150 MOD using thAPT as collateral" | | aptos_thala_redeem_mod | Redeem MOD for collateral | "Redeem 75 MOD tokens for thAPT" |

Native Staking Operations (2 tools)

| Tool Name | Description | Example Usage | |-----------|-------------|---------------| | aptos_stake_apt | Stake APT with a validator | "Stake 100 APT with validator 0x123..." | | aptos_unstake_apt | Unstake APT from a validator | "Unstake 50 APT from validator 0x123..." |

Example Interactions

Universal Pool Discovery

User: "Show me all available pools across all protocols on Aptos"

Agent: 
1. Uses aptos_joule_list_pools to show lending markets
2. Uses list_liquidswap_pools to show DEX pools  
3. Uses list_thala_pools to show Thala options
4. Uses list_echelon_markets to show Echelon lending rates
5. Provides comprehensive overview with rate comparisons

Cross-Protocol Lending Rate Comparison

User: "Compare lending rates for USDC across all protocols"

Agent:
1. Uses aptos_joule_list_pools to get Joule rates
2. Uses list_echelon_markets to get Echelon rates
3. Compares APY, liquidity, and additional rewards
4. Recommends optimal allocation strategy

Perpetual Trading Strategy

User: "Help me set up a long position on APT with proper risk management"

Agent:
1. Uses get_merkle_positions to check current exposure
2. Uses place_merkle_limit_order to enter position at target price
3. Sets up stop-loss and take-profit levels
4. Monitors position with regular updates

Cross-Protocol Yield Optimization

User: "Find the best yields for my USDC across all lending protocols"

Agent:
1. Uses aptos_joule_list_pools to check Joule rates
2. Uses list_echelon_markets to check Echelon rates
3. Factors in additional rewards and risks
4. Executes optimal allocation across protocols

DEX Aggregation for Best Rates

User: "Swap 1000 USDC for APT using the best available rate"

Agent:
1. Uses get_panora_quote to get aggregated pricing
2. Compares with direct Liquidswap rates
3. Uses swap_with_panora for optimal execution
4. Shows savings compared to single DEX

Complete Lending Workflow

User: "I want to use my APT as collateral to borrow USDC, then track my position"

Agent:
1. Uses aptos_joule_lend to deposit APT as collateral
2. Uses aptos_joule_borrow to borrow USDC against collateral
3. Uses aptos_joule_get_position to show health ratio and details
4. Sets up monitoring for liquidation risk

Advanced Liquidswap Operations

User: "Create a new trading pool for my token, add initial liquidity, 
       then show me the pool statistics"

Agent:
1. Uses aptos_create_pool to create the trading pair
2. Uses aptos_add_liquidity to provide initial liquidity
3. Shows pool statistics and fee earning potential
4. Provides ongoing pool management recommendations

Comprehensive Staking Strategy

User: "What are the best staking options for my 1000 APT?"

Agent:
1. Compares native staking vs liquid staking options
2. Shows yields for Thala liquid staking vs native validators
3. Recommends diversified approach using multiple protocols
4. Executes chosen strategy across different platforms

Protocol Integrations

Universal Pool Discovery

• Cross-protocol pool listing across all major DeFi protocols
• Real-time rate comparison for optimal yield farming
• Comprehensive market data with APY and liquidity metrics
• Unified discovery interface across all protocols

Liquidswap DEX

• Complete trading functionality with optimal routing
• Advanced liquidity management with fee optimization
• Pool creation and management for new trading pairs
• Real-time price monitoring and arbitrage detection

Joule Finance

• Professional lending platform with competitive rates
• Multi-asset collateral support for borrowing
• Automated reward claiming and compound strategies
• Risk management with health ratio monitoring

Echelon Finance

• High-performance lending protocol with parallel execution
• Comprehensive market listing with real-time APY data
• Advanced risk management and position tracking
• Cross-protocol arbitrage opportunities

MerkleTrade

• Perpetual futures trading with leverage up to 1000x
• Advanced order types (market, limit, stop-loss)
• Real-time position monitoring and risk management
• Professional trading interface for active traders
• Note: Requires @merkletrade/ts-sdk for full functionality

Panora Exchange

• DEX aggregation for optimal swap rates
• Cross-protocol liquidity access
• Minimal slippage through intelligent routing
• Best price discovery across all DEXes

Thala Finance

• Liquid staking - Keep liquidity while earning staking rewards
• MOD stablecoin - Collateralized debt position management
• Yield optimization through liquid staking derivatives
• Advanced DeFi composability with other protocols

Native Aptos Staking

• Validator selection with AI-driven recommendations
• Staking optimization based on performance metrics
• Automated management of staking positions

Troubleshooting

If you're using Ubuntu or another Linux environment with NVM, you'll need to manually configure the path. Follow these steps:

1. Install the Aptos MCP under your current NVM-managed Node.js version.

npm install -g @tamago-labs/aptos-mcp

2. Due to how NVM installs libraries, you may need to use absolute paths in your config. Replace the example values below with your actual username and Node version:

{
  "mcpServers": {
    "aptos-mcp": {
      "command": "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/node",
      "args": [
        "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/@tamago-labs/aptos-mcp",
        "--aptos_private_key=YOUR_PRIVATE_KEY",
        "--aptos_network=mainnet"
      ]
    }
  }
}

3. Restart Claude Desktop and it should work now.

Work with Local Files

When working with local files especially when using Aptos CLI tools for smart contract development to create, build, and test a Move package on your machine—you'll need to import an additional MCP server library of filesystem made by Claude team. Use with:

"filesystem": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "${workspaceFolder}"
  ],
  "disabled": false
}

workspaceFolder refers to your working directory. You can provide more than one argument. Subfolders or specific files can then be referenced in your AI prompt.

If you're using Linux and encounter issues during setup, please refer to the troubleshooting section.

License

This project is licensed under the MIT License.