readme.md•9.63 kB
# 🚀 Aptos Blockchain MCP
[](https://opensource.org/licenses/MIT)
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](#overview)
- [Available Tools](#available-tools)
- [Requirements](#requirements)
- [Setup](#setup)
- [Usage](#usage)
- [Environment Variables](#environment-variables)
- [Additional Resources](#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::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 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::coin::T')
- `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/](https://nodejs.org/))
- Aptos Private Key for signing transactions
- Access to Aptos testnet (default) or mainnet
## Setup
1. Clone the repository
```bash
git clone <your-repo-url>
cd aptos_mcp
```
2. Install dependencies
```bash
npm install
```
3. Build the project
```bash
npm run build
```
This creates the compiled JavaScript files in the `build/` directory.
## Testing
### Quick Test Setup
Run the automated setup and test script:
```bash
./setup-test.sh
```
This will:
- Install dependencies
- Build the project
- Run comprehensive tests
- Show you next steps
### Manual Testing Options
1. **Automated Test Suite:**
```bash
node test-mcp.js
```
2. **Interactive Example:**
```bash
node example-usage.js
```
3. **Manual JSON-RPC Testing:**
```bash
# 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](https://aptos.dev/tools/aptos-cli/install-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:
```bash
npm run dev
```
### MCP Server Configuration
Add the following entry to your MCP client configuration:
```json
{
"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:
1. **Prepare for deployment:**
```bash
./prepare-deployment.sh
```
2. **Push to GitHub:**
```bash
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](https://smithery.ai)
- Connect your GitHub account
- Add your repository as a new MCP server
- Deploy from the Deployments tab
4. **Use in Claude Desktop:**
```json
{
"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
```bash
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](https://aptos.dev)
- [Aptos TypeScript SDK](https://github.com/aptos-labs/aptos-ts-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Aptos Explorer (Testnet)](https://explorer.aptoslabs.com/?network=testnet)
- [Aptos Faucet (Testnet)](https://aptoslabs.com/testnet-faucet)
## 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.