Aptos Blockchain MCP

🚀 Aptos Blockchain MCP

The MCP server integrates Aptos blockchain access into AI applications, enabling interaction with several tools for native APT operations, custom coin management, and transaction handling.

Table of Contents

• Overview
• Available Tools
• Requirements
• Setup
• Usage
• Environment Variables
• Additional Resources

Overview

This MCP (Model Context Protocol) server provides a complete implementation for interacting with the Aptos blockchain. It allows AI applications to create accounts, transfer APT tokens, deploy and manage custom coins, mint tokens, and query transaction information on the Aptos testnet and mainnet.

Available Tools

Account Management

create_account

Description: Create a new Aptos account with a random private key. This generates a new account that can be used for transactions on the Aptos blockchain. Returns the account address, private key, and public key.

Input Parameters: None

get_account_info

Description: Get detailed information about an Aptos account including sequence number and authentication key. This is used for checking account status and transaction readiness.

Input Parameters:

• account_address (required): Aptos account address, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3

fund_account

Description: Fund an Aptos account using the testnet faucet. This is only available on testnet and is used to add APT tokens to an account for testing purposes.

Input Parameters:

• account_address (required): Aptos account address to fund
• amount (optional): Amount of APT to fund (default: 1 APT)

Native APT Operations

get_apt_balance

Description: Get the native APT token balance of an Aptos account. This is used for checking the current balance of APT tokens in an account.

Input Parameters:

• account_address (required): Aptos account address

transfer_apt

Description: Transfer native APT tokens to another Aptos account. This is used for sending APT tokens from your account to another address.

Input Parameters:

• recipient_address (required): Recipient Aptos address
• amount (required): Amount of APT to transfer (e.g., '1.5' for 1.5 APT)
• max_gas_amount (optional): Maximum gas amount for the transaction (default: 2000)

Custom Coin Operations

get_coin_balance

Description: Get the balance of a specific coin type for an Aptos account. This is used for checking the balance of custom coins or tokens.

Input Parameters:

• account_address (required): Aptos account address
• coin_type (required): Coin type identifier, e.g., '0x1::'

transfer_coin

Description: Transfer a specific coin type to another Aptos account. This is used for sending custom coins or tokens from your account to another address.

Input Parameters:

• recipient_address (required): Recipient Aptos address
• coin_type (required): Coin type identifier
• amount (required): Amount of coins to transfer (in smallest unit)
• max_gas_amount (optional): Maximum gas amount for the transaction (default: 2000)

deploy_coin

Description: Deploy a new custom coin/token on Aptos blockchain. This creates a new coin type that can be minted, transferred, and managed.

Input Parameters:

• name (required): Name of the coin (e.g., 'My Token')
• symbol (required): Symbol of the coin (e.g., 'MTK')
• decimals (optional): Number of decimal places (default: 8, range: 0-32)
• icon_url (optional): URL to the coin icon/logo
• project_url (optional): URL to the project website
• max_gas_amount (optional): Maximum gas amount (default: 5000)

mint_coin

Description: Mint new tokens of a previously deployed custom coin. Only the coin deployer can mint new tokens.

Input Parameters:

• coin_type (required): The coin type identifier (e.g., '0x123::')
• recipient_address (required): Address to receive the minted coins
• amount (required): Amount of coins to mint (in coin's base unit)
• max_gas_amount (optional): Maximum gas amount (default: 3000)

register_coin

Description: Register your account to receive a specific coin type. Required before receiving transfers of custom coins.

Input Parameters:

• coin_type (required): Coin type identifier to register for
• max_gas_amount (optional): Maximum gas amount (default: 1000)

Transaction Operations

get_transaction_status

Description: Get the status and details of a transaction by its hash. This is used for checking if a transaction was successful and getting detailed information about it.

Input Parameters:

• transaction_hash (required): Transaction hash to check

get_account_transactions

Description: Get recent transactions for an Aptos account. This is used for viewing transaction history and activity for an account.

Input Parameters:

• account_address (required): Aptos account address
• limit (optional): Maximum number of transactions to return (default: 10, max: 100)

Requirements

For this Aptos Blockchain MCP, you need:

• NodeJS v18 or higher (https://nodejs.org/)
• Aptos Private Key for signing transactions
• Access to Aptos testnet (default) or mainnet

Setup

1. Clone the repository

2. Install dependencies

3. Build the project

This creates the compiled JavaScript files in the build/ directory.

Testing

Quick Test Setup

Run the automated setup and test script:

This will:

• Install dependencies
• Build the project
• Run comprehensive tests
• Show you next steps

Manual Testing Options

1. Automated Test Suite:
   node test-mcp.js
2. Interactive Example:
   node example-usage.js
3. Manual JSON-RPC Testing:
   # List all tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | APTOS_MCP_PRIVATE_KEY="your-key" node build/index.js # Create account echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_account","arguments":{}}}' | APTOS_MCP_PRIVATE_KEY="your-key" node build/index.js
4. Real Aptos Testing:
   • Get a real private key from Aptos CLI
   • Fund your account using the testnet faucet
   • Test real transactions

See test-manual.md for detailed testing instructions.

Usage

Local Development

For local development and testing:

MCP Server Configuration

Add the following entry to your MCP client configuration:

Replace /path/to/aptos_mcp with the actual path to your installation and set your environment variables.

Smithery.ai Deployment

Deploy to Smithery.ai for easy access from any MCP-compatible AI application:

1. Prepare for deployment:
   ./prepare-deployment.sh
2. Push to GitHub:
   git init git add . git commit -m "Initial commit" git remote add origin https://github.com/YOUR_USERNAME/aptos-mcp.git git push -u origin main
3. Deploy on Smithery:
   • Visit smithery.ai
   • Connect your GitHub account
   • Add your repository as a new MCP server
   • Deploy from the Deployments tab
4. Use in Claude Desktop:
   { "mcpServers": { "aptos-mcp": { "command": "smithery", "args": ["@your-username/aptos-mcp"], "env": { "SMITHERY_CONFIG": "{\"aptosMcpPrivateKey\":\"0x...\",\"aptosMcpNetwork\":\"testnet\"}" } } } }

See DEPLOYMENT.md for detailed deployment instructions.

Environment Variables

Required

• APTOS_MCP_PRIVATE_KEY: Your Aptos account private key (hex format starting with 0x)

Optional

• APTOS_MCP_NETWORK: Network to connect to (testnet or mainnet, default: testnet)
• APTOS_MCP_NODE_URL: Custom node URL (optional, uses default network nodes)
• APTOS_MCP_FAUCET_URL: Custom faucet URL for testnet (optional, uses default faucet)

Example Configuration

⚠️ Security Note: Never commit your private key to version control. Use environment variables or secure key management systems.

Additional Resources

• Aptos Documentation
• Aptos TypeScript SDK
• Model Context Protocol
• Aptos Explorer (Testnet)
• Aptos Faucet (Testnet)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.