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) <!-- - Polygon (Chain ID: 137) - BNB Smart Chain (Chain ID: 56) - Arbitrum One (Chain ID: 42161) - Optimism (Chain ID: 10) - Avalanche C-Chain (Chain ID: 43114) - Fantom Opera (Chain ID: 250) --> - 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.