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

Related MCP server: Sui Butler

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)

Pool Discovery & Liquidity Management (3 tools)

Liquidswap DEX Operations (4 tools)

Joule Finance - Complete Lending Protocol (8 tools)

Echelon Finance - Lending Protocol (6 tools)

MerkleTrade - Perpetual Trading (4 tools)

Panora - DEX Aggregator (2 tools)

Thala Finance - Liquid Staking & Stablecoin (4 tools)

Native Staking Operations (2 tools)

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.