evm-mcp

Purpose

evm-mcp is an MCP (Model Context Protocol) server used to provide complete access to EVM JSON-RPC methods in AI programming environments such as Cursor and Claude Desktop. It enables AI to interact directly with any EVM-compatible blockchain, supporting networks such as Ethereum, Polygon, Arbitrum, Optimism, BSC, Avalanche, Base, and more, and is compatible with node providers such as Infura, Alchemy, QuickNode, local nodes, and custom RPC.

Main Capabilities

Blockchain Data Queries

Provides more than 20 RPC methods, including:

eth_blockNumber: Get the latest block number
eth_getBalance: Get an account balance
eth_getTransactionCount: Get the transaction count (nonce)
eth_getBlockByNumber: Get block information
eth_getTransactionByHash: Get transaction details
eth_getTransactionReceipt: Get a transaction receipt
eth_getCode: Get contract bytecode
eth_getStorageAt: Get a storage value
eth_call: Execute a contract call
eth_estimateGas: Estimate transaction gas
eth_sendRawTransaction: Send a signed transaction
eth_gasPrice: Get the current gas price

Transaction Simulation (Read-Only, Will Not Broadcast)

Transactions can be constructed in natural language and simulated against forked/overridden EVM state. Reports whether the transaction would succeed or revert, the revert reason (in plain English), estimated gas, and balance/state changes. Supports address aliases and ENS names (such as alice.eth). By default, the sender receives virtual ETH in order to simulate from any address; set fund: false to use the real balance.

simulate_native_transfer: Simulate sending the native currency
simulate_erc20_transfer: Simulate an ERC20 transfer (supports human-readable amounts)
simulate_contract_call: Encode a function signature and parameters and simulate the call- simulate_transaction: Simulate a raw transaction (from/to/value/data)
encode_function_data: Encode calldata from a human-readable signature (a pure helper tool, no RPC) These tools only use eth_call, eth_estimateGas, and debug_traceCall (when supported by the provider), and will never sign or send a real transaction. When debug_traceCall is available, real state diffs are used; otherwise, changes are inferred from the decoded intent.

Events and Logs

eth_getLogs: Get event logs
list_supported_networks: List configured networks and providers
list_known_addresses: List configured wallet aliases and known token/contract addresses
eth_chainId: Get the chain ID
net_version: Get the network version
net_listening: Check whether it is listening
net_peerCount: Get the peer count
web3_clientVersion: Get the client version
web3_sha3: Hash data using Keccak-256

Usage

Installation

One-click installation in Cursor is recommended (click the installation link), or install manually:

Requirements: Node.js 18+ and npm

Add to claude_desktop_config.json: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after configuration.

Environment Variable Configuration

At least one provider API key, custom provider, or custom network with rpcUrl is required.

Built-in providers (Infura / Alchemy): After setting the API key, the server automatically builds RPC URLs for supported networks. Each RPC tool accepts an optional network parameter (slug, name, or chain ID); when omitted, it uses DEFAULT_NETWORK.
Custom providers (CUSTOM_PROVIDERS): provide base URL templates and network-specific URLs. Absolute networkUrls are used directly (supporting {apiKey} substitution); relative paths (starting with /) are appended to the baseUrl.
Custom networks (CUSTOM_NETWORKS): register any chain by name, or route by setting a provider and adding a network slug to that provider's networkUrls.
Known addresses (KNOWN_ADDRESSES): register tokens and contracts by name, so that tools accept aliases such as USDC instead of raw hexadecimal addresses. Each entry targets a specific network. When eth_getBalance is called with a token alias, the server uses the first wallet configured in WALLET_ADDRESSES as the token holder.
Wallet addresses (WALLET_ADDRESSES): register personal wallets and contracts by alias, so you can use "check my personal wallet" instead of pasting a hexadecimal address. Address aliases apply to eth_getBalance, eth_getCode, eth_call, eth_getLogs, and other tools that accept address parameters. Use list_known_addresses to discover configured aliases.

Configuration changes require restarting the MCP server.

Supported built-in networks

Ethereum: Mainnet, Sepolia
Polygon: Mainnet, Amoy
Arbitrum: One, Sepolia
Optimism: Mainnet, Sepolia
BNB Smart Chain: Mainnet, Testnet
Avalanche: C-Chain
Base: Mainnet, Sepolia
Any EVM-compatible chain is supported via CUSTOM_NETWORKS

Example operations

Get the latest block number
Check an account balance using a hexadecimal address or a configured alias
View transaction information
Execute contract calls
Query contract events

Use cases

Blockchain analysis: query transaction data, balances, and contract state
DeFi applications: monitor token balances, transaction receipts, and smart contract calls
NFT projects: track transfers, metadata, and collection statistics
Development tools: debug transactions, estimate gas, and testsmart contracts
Monitoring: observe specific events and transaction patterns
Research: analyze blockchain data across multiple EVM networks

Limitations

Transaction simulation tools only use eth_call, eth_estimateGas, and debug_traceCall (when supported by the provider), and never sign or send real transactions.
When debug_traceCall is unavailable, state changes are inferred from the decoded intent and may be imprecise.
Configuration changes require restarting the MCP server.
Requires Node.js 18+ and npm.
Requires at least one provider API key, custom provider, or custom network with an rpcUrl.

Technical details

Built with: Node.js, TypeScript, MCP SDK, Ethers.js
Dependencies: @modelcontextprotocol/sdk, ethers, zod
Platforms: macOS, Windows, Linux
License: MIT