Blockchain MCP Server DEMO

A comprehensive Model Context Protocol (MCP) server for interacting with multiple EVM-compatible blockchains. This server provides tools and resources for blockchain data access and analysis.

Features

🔗 Multi-Chain Support

• Ethereum Mainnet (Chain ID: 1)

• Conflux eSpace (Chain ID: 1030)

🛠️ Tools (POST-like endpoints)

1. get_chains - Get list of supported blockchain networks
2. get_rpc_methods - Get supported RPC method list
3. call_rpc - Execute arbitrary RPC method calls
4. get_latest_block - Get latest block number for a chain
5. get_transaction - Get transaction details by hash
6. get_address - Get address balance and information
7. get_block - Get block information by number

📚 Resources (GET-like endpoints)

1. blockchain://transaction/{hash} - Fetch transaction details (cross-chain search)
2. blockchain://block/{chainId}/{number} - Fetch block information
3. blockchain://address/{chainId}/{address} - Fetch address information and balance
4. blockchain://chains - List all supported blockchain networks

Technology Stack

• TypeScript - Type-safe development
• Viem - Modern Ethereum library with excellent TypeScript support
• Model Context Protocol (MCP) - Standardized AI-blockchain communication
• Zod - Runtime type validation

Installation

1. Clone the repository:

git clone <repository-url>
cd blockchain-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Start the server:

npm start

Usage Examples

Tools

Get supported chains

// 获取所有支持的区块链网络
await callTool("get_chains", {});

Get transaction information

// 获取交易信息
await callTool("get_transaction", {
  hash: "0x1234567890abcdef...",
  chainId: 1  // optional, will search all chains if not provided
});

Get address information

// 获取地址信息
await callTool("get_address", {
  address: "0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00",
  chainId: 1
});

Execute RPC call

// 获取以太坊主网最新区块号
await callTool("call_rpc", {
  method: "eth_blockNumber",
  params: [],
  chainId: 1
});

// 获取地址余额
await callTool("call_rpc", {
  method: "eth_getBalance", 
  params: ["0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00", "latest"],
  chainId: 1
});

Resources

Access transaction data

// 跨链查询交易 (will search all supported chains)
const txResource = await getResource("blockchain://transaction/0x1234567890abcdef...");

Access block data

// 获取以太坊主网特定区块
const block = await getResource("blockchain://block/1/19000000");

// 获取Polygon特定区块
const polygonBlock = await getResource("blockchain://block/137/12345678");

Access address data

// 获取地址信息
const addressInfo = await getResource("blockchain://address/1/0x742de6d65963b2c3a5e8e3b8c7cb56c6f78e0c00");

Access supported chains

// 获取所有支持的区块链网络
const chains = await getResource("blockchain://chains");

Supported RPC Methods

The server supports the following standard Ethereum JSON-RPC methods:

• eth_getBalance - Get account balance
• eth_getTransactionByHash - Get transaction by hash
• eth_getTransactionReceipt - Get transaction receipt
• eth_getBlockByNumber - Get block by number
• eth_getBlockByHash - Get block by hash
• eth_getTransactionCount - Get account nonce
• eth_getCode - Get contract code
• eth_call - Execute contract call
• eth_estimateGas - Estimate gas for transaction
• eth_gasPrice - Get current gas price
• eth_blockNumber - Get latest block number
• eth_chainId - Get chain ID
• net_version - Get network version
• web3_clientVersion - Get client version

API Reference

Tools

get_chains

Returns a list of all supported blockchain networks.

Parameters: None

Response:

[
  {
    "chainId": 1,
    "name": "Ethereum Mainnet",
    "symbol": "ETH",
    "rpcUrls": [...],
    "blockExplorerUrls": [...],
    "nativeCurrency": {...}
  }
]

get_transaction

Get detailed transaction information.

Parameters:

• hash (string): Transaction hash
• chainId (number, optional): Chain ID to search on

Response:

{
  "hash": "0x...",
  "blockNumber": 19000000,
  "from": "0x...",
  "to": "0x...",
  "value": "1.0",
  "gasPrice": "0.00002",
  "gasUsed": "21000",
  "chainId": 1,
  "status": 1
}

get_address

Get address balance and information.

Parameters:

• address (string): Ethereum address
• chainId (number): Chain ID

Response:

{
  "address": "0x...",
  "balance": "10.5",
  "nonce": 42,
  "code": null,
  "chainId": 1
}

call_rpc

Execute arbitrary RPC method calls.

Parameters:

• method (string): RPC method name
• params (array, optional): Method parameters
• chainId (number, optional): Chain ID (default: 1)

Response: Raw RPC response

Error Handling

The server includes comprehensive error handling:

• Network failures: Automatic failover between RPC endpoints
• Invalid parameters: Input validation using Zod schemas
• Chain unavailability: Graceful handling when chains are down
• Transaction not found: Cross-chain search with clear error messages

Architecture

src/
├── index.ts              # Main MCP server implementation
├── blockchain-service.ts # Blockchain interaction service (using viem)
├── config.ts            # Chain configurations and constants
└── types.ts             # TypeScript interfaces and schemas

Key Components

1. BlockchainService: Manages connections to multiple EVM chains using viem clients
2. MCP Server: Exposes tools and resources following MCP specification
3. Type Safety: Full TypeScript support with Zod validation and viem's excellent types
4. Multi-chain Support: Seamless interaction across different networks

Why Viem?

This project uses viem instead of ethers for several advantages:

• Better TypeScript Support: Native TypeScript with strict typing
• Modern API: Functional approach with better tree-shaking
• Performance: Optimized for speed and bundle size
• Reliability: Built-in retry logic and better error handling
• Future-proof: Actively maintained with cutting-edge features

Testing

You can test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Configuration

The server automatically connects to multiple blockchain networks using public RPC endpoints. You can customize RPC endpoints by modifying the src/config.ts file.

Adding New Chains

To add support for new EVM-compatible chains, update the SUPPORTED_CHAINS object in src/config.ts:

export const SUPPORTED_CHAINS: Record<number, ChainConfig> = {
  // ... existing chains
  
  // New chain example
  YOUR_CHAIN_ID: {
    chainId: YOUR_CHAIN_ID,
    name: "Your Chain Name",
    symbol: "TOKEN",
    rpcUrls: [
      "https://rpc.yourchain.com",
      "https://backup-rpc.yourchain.com"
    ],
    blockExplorerUrls: ["https://explorer.yourchain.com"],
    nativeCurrency: {
      name: "Your Token",
      symbol: "TOKEN",
      decimals: 18
    }
  }
};

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For questions or issues, please open an issue on the GitHub repository.