{
  "markdown": "# evmcp\n\n> EVM + MCP — give your AI assistant blockchain superpowers.\n\nMCP 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.\n\n## How it Works\n\nEVMCP implements the [Model Context Protocol](https://modelcontextprotocol.io/) (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.\n\nWhat 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.\n\n## Quick Start\n\n### With Claude Desktop\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"evmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"evmcp\"],\n      \"env\": { \"ALCHEMY_API_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n### With Claude Code\n```bash\nclaude mcp add evmcp -- npx -y evmcp\n```\n\n## Supported Chains\n\n| Chain | Chain ID | Native Token | Companion Contracts |\n|-------|----------|--------------|---------------------|\n| Base | 8453 | ETH | Not yet deployed |\n| Optimism | 10 | ETH | Not yet deployed |\n| Avalanche C-Chain | 43114 | AVAX | Deployed |\n| Celo | 42220 | CELO | Deployed |\n| Arbitrum One | 42161 | ETH | Not yet deployed |\n\nEthereum mainnet (chain ID 1) is also supported for ENS resolution only.\n\n## Tools (29 total)\n\n### Balance (3)\n| Tool | Description |\n|------|-------------|\n| `getBalance` | Get the native token balance (ETH/AVAX/CELO) of an address on a specific chain |\n| `getTokenBalance` | Get the ERC20 token balance of an address on a specific chain |\n| `getMultiChainBalance` | Get the native token balance of an address across all 5 supported chains in parallel |\n\n### Block (3)\n| Tool | Description |\n|------|-------------|\n| `getBlock` | Get a block by its hash on a specific chain |\n| `getBlockByNumber` | Get a block by its number on a specific chain, or pass \"latest\" for the most recent block |\n| `getLatestBlock` | Get the latest block number, timestamp, and base fee for a specific chain |\n\n### Transaction (3)\n| Tool | Description |\n|------|-------------|\n| `getTransaction` | Get a transaction by its hash on a specific chain |\n| `getTransactionReceipt` | Get the receipt for a transaction including status, gasUsed, and logs |\n| `decodeTransaction` | Decode a transaction's function call using a provided ABI |\n\n### Contract (3)\n| Tool | Description |\n|------|-------------|\n| `readContract` | Call a read-only function on a smart contract with a provided ABI |\n| `getContractCode` | Check if an address has contract code deployed, with bytecode length and hash |\n| `getStorageAt` | Read the raw value of a storage slot at a specific address |\n\n### Token (2)\n| Tool | Description |\n|------|-------------|\n| `getERC20Info` | Get ERC20 token metadata including name, symbol, decimals, and total supply |\n| `getTokenAllowance` | Get the ERC20 token allowance granted by an owner to a spender |\n\n### Gas (3)\n| Tool | Description |\n|------|-------------|\n| `getGasPrice` | Get current gas price and EIP-1559 fee data for a specific chain |\n| `estimateGas` | Estimate gas for a transaction on a specific chain |\n| `compareGasAcrossChains` | Compare current gas prices across all 5 supported chains |\n\n### ENS (2)\n| Tool | Description |\n|------|-------------|\n| `resolveENS` | Resolve an ENS name (e.g. vitalik.eth) to an Ethereum address via Ethereum L1 |\n| `lookupAddress` | Reverse lookup an address to its ENS name via Ethereum L1 |\n\n### Events (2)\n| Tool | Description |\n|------|-------------|\n| `getContractEvents` | Get event logs emitted by a contract on a specific chain |\n| `decodeEventLog` | Decode a raw event log using a provided ABI |\n\n### Chain and Health (3)\n| Tool | Description |\n|------|-------------|\n| `getChainInfo` | Get chain name, chain ID, current block number, block time, and native symbol |\n| `isContractDeployed` | Check if an address has contract code deployed on all 5 supported chains |\n| `healthCheck` | Test connectivity to all 6 RPC endpoints (Ethereum, Base, Optimism, Avalanche, Celo, Arbitrum) |\n\n### Batch (1)\n| Tool | Description |\n|------|-------------|\n| `batchQuery` | Execute multiple read calls in a single RPC request using Multicall3 |\n\n### Cross-Chain (2)\n| Tool | Description |\n|------|-------------|\n| `compareBalances` | Compare native token balances for an address across all 5 chains |\n| `crossChainActivity` | Check transaction counts for an address across all 5 chains |\n\n### Registry (1)\n| Tool | Description |\n|------|-------------|\n| `queryRegistry` | Read registered tool metadata from the on-chain MCPRegistry companion contract |\n\n### Optimizer (1)\n| Tool | Description |\n|------|-------------|\n| `gasOptimizer` | Recommends the cheapest chain for a transaction, accounting for L1 data fees on Base/Optimism/Arbitrum |\n\n## Resources (4)\n\n| URI Pattern | Description | Cache TTL |\n|-------------|-------------|-----------|\n| `chain://{chainId}/status` | Current block height and gas price for a chain | 12s |\n| `chain://{chainId}/gas` | Base fee, gas price, and priority fee in gwei | 12s |\n| `chain://{chainId}/tokens/popular` | Popular token addresses and decimals (hardcoded for v1) | 1 hour |\n| `evmcp://chains` | All supported chains with IDs, symbols, and companion contract addresses | Static |\n\nSupported chain IDs for templated resources: `8453` (Base), `10` (Optimism), `43114` (Avalanche), `42220` (Celo), `42161` (Arbitrum).\n\n## Prompts (4)\n\n| Prompt | Arguments | Description |\n|--------|-----------|-------------|\n| `analyze-wallet` | `address` | Multi-chain balance and activity analysis of a wallet |\n| `audit-contract` | `contractAddress`, `chain` | Basic inspection and audit workflow for a smart contract |\n| `compare-chains` | *(none)* | Compare gas costs, speed, and characteristics across all chains |\n| `investigate-tx` | `txHash`, `chain` | Decode, analyze, and trace a transaction in detail |\n\n## Companion Contracts\n\nFour 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.\n\n### Avalanche C-Chain (43114)\n\n| Contract | Address |\n|----------|---------|\n| MCPRegistry | `0x62402b65bfb4Fd022285A6FC2F26d8caEEc3D055` |\n| BatchQuery | `0xfDc19e0617AdF1811A68Aa1575409F3769f39491` |\n| EventAggregator | `0xECE24a53A28F088351EC2Da258f78479e81A8007` |\n| CrossChainCache | `0x0899a6Ef23c6B39A4D9B877B219645B89209A670` |\n\n### Celo (42220)\n\n| Contract | Address |\n|----------|---------|\n| MCPRegistry | `0x62402b65bfb4Fd022285A6FC2F26d8caEEc3D055` |\n| BatchQuery | `0xfDc19e0617AdF1811A68Aa1575409F3769f39491` |\n| EventAggregator | `0xECE24a53A28F088351EC2Da258f78479e81A8007` |\n| CrossChainCache | `0x0899a6Ef23c6B39A4D9B877B219645B89209A670` |\n\n### Contract Descriptions\n\n- **MCPRegistry** -- On-chain metadata for all EVMCP tools (names, descriptions, versions). Owner-only writes.\n- **BatchQuery** -- Optimized batch reads via Multicall3. Includes multi-balance, multi-contract-check, and multi-token-balance helpers.\n- **EventAggregator** -- Caches event count summaries per contract. Updated by the admin CLI.\n- **CrossChainCache** -- Stores balance snapshots for cross-chain queries. Updated by the admin CLI.\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ALCHEMY_API_KEY` | Yes* | Alchemy API key (covers all chains) |\n| `BASE_RPC_URL` | No* | Override RPC URL for Base |\n| `OPTIMISM_RPC_URL` | No* | Override RPC URL for Optimism |\n| `AVALANCHE_RPC_URL` | No* | Override RPC URL for Avalanche |\n| `CELO_RPC_URL` | No* | Override RPC URL for Celo |\n| `ARBITRUM_RPC_URL` | No* | Override RPC URL for Arbitrum |\n| `ETHEREUM_RPC_URL` | No | Override RPC URL for ENS resolution |\n| `CACHE_TTL_SECONDS` | No | Cache TTL in seconds (default: 15) |\n| `CACHE_MAX_ENTRIES` | No | Max cache entries (default: 1000) |\n| `LOG_LEVEL` | No | debug, info, warn, or error (default: info) |\n| `USE_TESTNETS` | No | Use testnet chains (default: false) |\n\n| `TRANSPORT` | No | `stdio` (default) or `http` for Streamable HTTP transport |\n| `HTTP_PORT` | No | Port for HTTP transport (default: 3402) |\n| `X402_ENABLED` | No | Enable x402 payment gating on HTTP transport |\n| `X402_PAYEE_ADDRESS` | No** | USDC receive address on Base |\n| `X402_FACILITATOR_URL` | No | x402 facilitator URL (has default) |\n\n*Provide either `ALCHEMY_API_KEY` or all five individual chain RPC URLs.\n**Required when `X402_ENABLED=true`.\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm inspect          # MCP Inspector UI at localhost:6274\npnpm test             # Unit tests\npnpm typecheck        # Type check\npnpm lint             # ESLint\n```\n\n## License\n\nMIT\n",
  "bytes": 9212,
  "sha": "ed61c13ce5649aaedef3af4487486f20e59bd27a0a92c79270de5b9d97221fff",
  "repo_slug": "siriuslattice/evmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_siriuslattice_evmcp_f87e8a65/readme"
}