Aptos MCP Server

A Model Context Protocol (MCP) server for interacting with the Aptos blockchain testnet. This server provides AI assistants with the ability to perform blockchain operations, query data, and manage digital assets on Aptos.

Features

🔐 Account Management ff

• Generate new Aptos accounts
• Get account information and balances
• Fund accounts from t estnet faucet
• Validate addresses and check account existence. d
• Query account resources

💸 Transaction Operations

• Transfer APT tokens between accounts
• Build, sign, and submit transactions
• Simulate transactions for gas estimation
• Track transaction status and history
• Execute custom smart contract functions

🔍 Blockchain Queries

• Get current blockchain information
• Query blocks by height or version
• Search for events and activities
• Get gas price estimations
• Call view functions (read-only)
• Query table items

🎨 Token & NFT Management

• Get account token balances (fungible tokens)
• Query owned NFTs and collections
• Transfer tokens and NFTs
• Get token and collection metadata
• Track token-related activities
• Deploy new fungible tokens
• Create NFT collections
• Mint NFTs and fungible tokens

Installation

Local Development

npm install
npm run build

mcp.so Hosting

This server is ready for deployment on mcp.so:

1. Upload to GitHub: Push your code to a public repository
2. Submit to mcp.so: Use the submission form
3. Automatic hosting: Supports both stdio and REST transports
4. Docker support: Includes Dockerfile for containerized deployment

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "aptos": {
      "command": "node",
      "args": ["/path/to/aptos-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

Standalone Testing

# Run in stdio mode (default)
node build/index.js

# Run in REST mode for web hosting
mode=rest node build/index.js

# Run tests
npm test

# Run with coverage
npm run test:coverage

Available Tools

Account Tools

• generate_account - Generate a new Aptos account
• get_account_info - Get detailed account information
• get_account_balance - Check APT balance
• fund_account - Fund account from testnet faucet
• check_account_exists - Verify if account exists
• get_account_resources - Get all account resources

Transaction Tools

• transfer_apt - Transfer APT tokens
• get_transaction - Get transaction details by hash
• simulate_transaction - Simulate transaction for gas estimation
• get_account_transactions - Get account transaction history
• execute_function - Execute custom smart contract functions

Query Tools

• get_chain_info - Get blockchain information
• get_block - Get block data by height/version
• get_events - Query blockchain events
• get_account_modules - Get published modules
• get_gas_price - Get current gas price
• get_table_item - Query table items
• view_function - Call read-only functions

Token Tools

• get_account_tokens - Get owned NFTs
• get_token_data - Get token metadata
• get_collection_data - Get collection information
• get_account_coin_balances - Get all coin balances
• transfer_token - Transfer NFTs
• get_account_token_activities - Get token activity history
• deploy_fungible_token - Deploy a new fungible token
• create_nft_collection - Create a new NFT collection
• mint_nft - Mint an NFT in an existing collection
• mint_fungible_token - Mint fungible tokens to an account

Examples

Generate and Fund Account

// Generate a new account
const account = aptosClient.generateAccount();
console.log(`Address: ${account.accountAddress}`);

// Fund from testnet faucet
await aptosClient.fundAccount(account.accountAddress.toString());

// Check balance
const balance = await aptosClient.getAccountBalance(account.accountAddress.toString());
console.log(`Balance: ${balance} APT`);

Transfer APT

// Transfer 1 APT from sender to recipient
const result = await transferAPT({
  fromPrivateKey: "0x...",
  toAddress: "0x...",
  amount: 1.0
});

Query Blockchain Data

// Get current blockchain info
const chainInfo = await aptosClient.getChainInfo();

// Get latest block
const block = await aptosClient.getClient().getBlockByHeight({
  blockHeight: chainInfo.block_height
});

Deploy and Mint Tokens

// Deploy a new fungible token
const deployResult = await deployFungibleToken({
  creatorPrivateKey: "0x...",
  name: "My Token",
  symbol: "MTK",
  decimals: 8
});

// Create an NFT collection
const collectionResult = await createNFTCollection({
  creatorPrivateKey: "0x...",
  name: "My NFT Collection",
  description: "A collection of unique digital assets",
  uri: "https://example.com/collection.json"
});

// Mint an NFT in the collection
const nftResult = await mintNFT({
  creatorPrivateKey: "0x...",
  collectionName: "My NFT Collection",
  tokenName: "NFT #1",
  description: "First NFT in the collection",
  uri: "https://example.com/nft1.json",
  recipientAddress: "0x..."
});

// Mint fungible tokens
const mintResult = await mintFungibleToken({
  creatorPrivateKey: "0x...",
  recipientAddress: "0x...",
  amount: 1000
});

Development

Project Structure

src/
├── index.ts              # Main MCP server entry point
├── aptos-client.ts       # Aptos client wrapper
└── tools/
    ├── account-tools.ts  # Account management tools
    ├── transaction-tools.ts # Transaction tools
    ├── query-tools.ts    # Blockchain query tools
    └── token-tools.ts    # Token and NFT tools

Testing

# Run all tests
npm test

# Run specific test file
npm test -- aptos-client.test.ts

# Run with coverage
npm run test:coverage

Building

# Build TypeScript
npm run build

# Clean build directory
npm run clean

Configuration

The server is configured for Aptos testnet by default. Key configuration:

• Network: Testnet
• Timeout: 30 seconds for requests
• Gas Limits: Configurable per transaction
• Error Handling: Comprehensive error messages

Security Notes

⚠️ Important Security Considerations:

1. Private Keys: Never share or expose private keys
2. Testnet Only: This server is configured for testnet only
3. Rate Limiting: Testnet faucet has rate limits
4. Gas Costs: Always simulate transactions first
5. Validation: All addresses and inputs are validated

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the Aptos documentation
• Review the MCP specification
• Open an issue in this repository

Deployment to mcp.so

This server is designed to be deployed to mcp.so. The build output in build/index.js is the entry point for the MCP server.