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
| Chain | Chain ID | Native Token | Companion Contracts |
|---|
| Base | 8453 | ETH | Not yet deployed |
| Optimism | 10 | ETH | Not yet deployed |
| Avalanche C-Chain | 43114 | AVAX | Deployed |
| Celo | 42220 | CELO | Deployed |
| Arbitrum One | 42161 | ETH | Not yet deployed |
Ethereum mainnet (chain ID 1) is also supported for ENS resolution only.
Tools (29 total)
Balance (3)
| Tool | Description |
|---|
getBalance | Get the native token balance (ETH/AVAX/CELO) of an address on a specific chain |
getTokenBalance | Get the ERC20 token balance of an address on a specific chain |
getMultiChainBalance | Get the native token balance of an address across all 5 supported chains in parallel |
Block (3)
| Tool | Description |
|---|
getBlock | Get a block by its hash on a specific chain |
getBlockByNumber | Get a block by its number on a specific chain, or pass "latest" for the most recent block |
getLatestBlock | Get the latest block number, timestamp, and base fee for a specific chain |
Transaction (3)
| Tool | Description |
|---|
getTransaction | Get a transaction by its hash on a specific chain |
getTransactionReceipt | Get the receipt for a transaction including status, gasUsed, and logs |
decodeTransaction | Decode a transaction's function call using a provided ABI |
Contract (3)
| Tool | Description |
|---|
readContract | Call a read-only function on a smart contract with a provided ABI |
getContractCode | Check if an address has contract code deployed, with bytecode length and hash |
getStorageAt | Read the raw value of a storage slot at a specific address |
Token (2)
| Tool | Description |
|---|
getERC20Info | Get ERC20 token metadata including name, symbol, decimals, and total supply |
getTokenAllowance | Get the ERC20 token allowance granted by an owner to a spender |
Gas (3)
| Tool | Description |
|---|
getGasPrice | Get current gas price and EIP-1559 fee data for a specific chain |
estimateGas | Estimate gas for a transaction on a specific chain |
compareGasAcrossChains | Compare current gas prices across all 5 supported chains |
ENS (2)
| Tool | Description |
|---|
resolveENS | Resolve an ENS name (e.g. vitalik.eth) to an Ethereum address via Ethereum L1 |
lookupAddress | Reverse lookup an address to its ENS name via Ethereum L1 |
Events (2)
| Tool | Description |
|---|
getContractEvents | Get event logs emitted by a contract on a specific chain |
decodeEventLog | Decode a raw event log using a provided ABI |
Chain and Health (3)
| Tool | Description |
|---|
getChainInfo | Get chain name, chain ID, current block number, block time, and native symbol |
isContractDeployed | Check if an address has contract code deployed on all 5 supported chains |
healthCheck | Test connectivity to all 6 RPC endpoints (Ethereum, Base, Optimism, Avalanche, Celo, Arbitrum) |
Batch (1)
| Tool | Description |
|---|
batchQuery | Execute multiple read calls in a single RPC request using Multicall3 |
Cross-Chain (2)
| Tool | Description |
|---|
compareBalances | Compare native token balances for an address across all 5 chains |
crossChainActivity | Check transaction counts for an address across all 5 chains |
Registry (1)
| Tool | Description |
|---|
queryRegistry | Read registered tool metadata from the on-chain MCPRegistry companion contract |
Optimizer (1)
| Tool | Description |
|---|
gasOptimizer | Recommends the cheapest chain for a transaction, accounting for L1 data fees on Base/Optimism/Arbitrum |
Resources (4)
| URI Pattern | Description | Cache TTL |
|---|
chain://{chainId}/status | Current block height and gas price for a chain | 12s |
chain://{chainId}/gas | Base fee, gas price, and priority fee in gwei | 12s |
chain://{chainId}/tokens/popular | Popular token addresses and decimals (hardcoded for v1) | 1 hour |
evmcp://chains | All supported chains with IDs, symbols, and companion contract addresses | Static |
Supported chain IDs for templated resources: 8453 (Base), 10 (Optimism), 43114 (Avalanche), 42220 (Celo), 42161 (Arbitrum).
Prompts (4)
| Prompt | Arguments | Description |
|---|
analyze-wallet | address | Multi-chain balance and activity analysis of a wallet |
audit-contract | contractAddress, chain | Basic inspection and audit workflow for a smart contract |
compare-chains | (none) | Compare gas costs, speed, and characteristics across all chains |
investigate-tx | txHash, chain | Decode, analyze, and trace a transaction in detail |
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)
| Contract | Address |
|---|
| MCPRegistry | 0x62402b65bfb4Fd022285A6FC2F26d8caEEc3D055 |
| BatchQuery | 0xfDc19e0617AdF1811A68Aa1575409F3769f39491 |
| EventAggregator | 0xECE24a53A28F088351EC2Da258f78479e81A8007 |
| CrossChainCache | 0x0899a6Ef23c6B39A4D9B877B219645B89209A670 |
Celo (42220)
| Contract | Address |
|---|
| MCPRegistry | 0x62402b65bfb4Fd022285A6FC2F26d8caEEc3D055 |
| BatchQuery | 0xfDc19e0617AdF1811A68Aa1575409F3769f39491 |
| EventAggregator | 0xECE24a53A28F088351EC2Da258f78479e81A8007 |
| CrossChainCache | 0x0899a6Ef23c6B39A4D9B877B219645B89209A670 |
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
| Variable | Required | Description |
|---|
ALCHEMY_API_KEY | Yes* | Alchemy API key (covers all chains) |
BASE_RPC_URL | No* | Override RPC URL for Base |
OPTIMISM_RPC_URL | No* | Override RPC URL for Optimism |
AVALANCHE_RPC_URL | No* | Override RPC URL for Avalanche |
CELO_RPC_URL | No* | Override RPC URL for Celo |
ARBITRUM_RPC_URL | No* | Override RPC URL for Arbitrum |
ETHEREUM_RPC_URL | No | Override RPC URL for ENS resolution |
CACHE_TTL_SECONDS | No | Cache TTL in seconds (default: 15) |
CACHE_MAX_ENTRIES | No | Max cache entries (default: 1000) |
LOG_LEVEL | No | debug, info, warn, or error (default: info) |
USE_TESTNETS | No | Use testnet chains (default: false) |
| 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