evmcp

EVM + MCP — give your AI assistant blockchain superpowers.

MCP server providing real-time access to on-chain data across Base, Optimism, Avalanche, Celo, and Arbitrum, with companion smart contracts deployed on-chain for batch queries and cross-chain data.

How it Works

EVMCP implements the Model Context Protocol (MCP), a standard that lets AI assistants call external tools. When connected, your AI assistant gains 28 read-only blockchain tools it can invoke to query balances, decode transactions, compare gas prices, and more across five EVM chains.

What sets EVMCP apart is its companion smart contracts — four Solidity contracts deployed on Avalanche and Celo that enable batch queries via Multicall3, an on-chain tool registry, event aggregation, and cross-chain balance caching. The MCP server reads from these contracts; all write operations are performed separately by an admin CLI.

Quick Start

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "evmcp": {
      "command": "npx",
      "args": ["-y", "evmcp"],
      "env": { "ALCHEMY_API_KEY": "your_key_here" }
    }
  }
}

With Claude Code

claude mcp add evmcp -- npx -y evmcp

Supported Chains

Ethereum mainnet (chain ID 1) is also supported for ENS resolution only.

Tools (29 total)

Balance (3)

Block (3)

Transaction (3)

Contract (3)

Token (2)

Gas (3)

ENS (2)

Events (2)

Chain and Health (3)

Batch (1)

Cross-Chain (2)

Registry (1)

Optimizer (1)

Resources (4)

Supported chain IDs for templated resources: 8453 (Base), 10 (Optimism), 43114 (Avalanche), 42220 (Celo), 42161 (Arbitrum).

Prompts (4)

Companion Contracts

Four Solidity contracts are deployed on Avalanche and Celo. The MCP server reads from these contracts to provide batch queries, on-chain tool metadata, and cross-chain data. Base and Optimism deployments are planned.

Avalanche C-Chain (43114)

Celo (42220)

Contract Descriptions

• MCPRegistry -- On-chain metadata for all EVMCP tools (names, descriptions, versions). Owner-only writes.
• BatchQuery -- Optimized batch reads via Multicall3. Includes multi-balance, multi-contract-check, and multi-token-balance helpers.
• EventAggregator -- Caches event count summaries per contract. Updated by the admin CLI.
• CrossChainCache -- Stores balance snapshots for cross-chain queries. Updated by the admin CLI.

Environment Variables

| TRANSPORT | No | stdio (default) or http for Streamable HTTP transport | | HTTP_PORT | No | Port for HTTP transport (default: 3402) | | X402_ENABLED | No | Enable x402 payment gating on HTTP transport | | X402_PAYEE_ADDRESS | No** | USDC receive address on Base | | X402_FACILITATOR_URL | No | x402 facilitator URL (has default) |

*Provide either ALCHEMY_API_KEY or all five individual chain RPC URLs. **Required when X402_ENABLED=true.

Development

pnpm install
pnpm build
pnpm inspect          # MCP Inspector UI at localhost:6274
pnpm test             # Unit tests
pnpm typecheck        # Type check
pnpm lint             # ESLint

License

MIT