🚀 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
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 fundamount(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 addressamount(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 addresscoin_type(required): Coin type identifier, e.g., '0x1::aptos_coin::AptosCoin'
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 addresscoin_type(required): Coin type identifieramount(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/logoproject_url(optional): URL to the project websitemax_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::coin::T')recipient_address(required): Address to receive the minted coinsamount(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 formax_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 addresslimit(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
- Clone the repository
git clone <your-repo-url>
cd aptos_mcp
- Install dependencies
npm install
- Build the project
npm run build
This creates the compiled JavaScript files in the build/ directory.
Testing
Quick Test Setup
Run the automated setup and test script:
./setup-test.sh
This will:
- Install dependencies
- Build the project
- Run comprehensive tests
- Show you next steps
Manual Testing Options
-
Automated Test Suite:
node test-mcp.js -
Interactive Example:
node example-usage.js -
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 -
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:
npm run dev
MCP Server Configuration
Add the following entry to your MCP client configuration:
{
"mcpServers": {
"aptos-mcp": {
"command": "node",
"args": [
"/path/to/aptos_mcp/build/index.js"
],
"env": {
"APTOS_MCP_PRIVATE_KEY": "0x1234567890abcdef...",
"APTOS_MCP_NETWORK": "testnet"
}
}
}
}
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:
-
Prepare for deployment:
./prepare-deployment.sh -
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 -
Deploy on Smithery:
- Visit smithery.ai
- Connect your GitHub account
- Add your repository as a new MCP server
- Deploy from the Deployments tab
-
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 (testnetormainnet, 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
export APTOS_MCP_PRIVATE_KEY="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
export APTOS_MCP_NETWORK="testnet"
⚠️ 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.