EVM MCP Server

A comprehensive Model Context Protocol (MCP) server that provides complete access to Ethereum Virtual Machine (EVM) JSON-RPC methods. Works with any EVM-compatible node provider including Infura, Alchemy, QuickNode, local nodes, and more.

🚀 Quick Start

1. Install and build:

   npm install npm run build

2. Configure Claude Desktop:

   • Open Claude Desktop Settings (Cmd/Ctrl + ,)

   • Add MCP server with command: node /path/to/evm-mcp/build/index.js

   • Set environment variables:

     { "RPC_URL": "https://mainnet.infura.io/v3/YOUR_API_KEY", "CHAIN_ID": "1" }

3. Test it: Ask Claude "What's the latest Ethereum block number?"

Features

This MCP server provides access to all major EVM JSON-RPC methods through 20+ specialized tools:

🌐 Web3 Methods

web3_clientVersion

Returns the current client version of the connected node.

web3_sha3

Computes the Keccak-256 hash of the given data.

🔢 Blockchain Data Methods

eth_blockNumber

Returns the number of the most recent block.

eth_getBalance

Returns the balance of an account at a specified block.

eth_getTransactionCount

Returns the number of transactions sent from an address (nonce).

eth_getBlockByNumber

Returns information about a block by block number.

eth_getTransactionByHash

Returns transaction information by transaction hash.

eth_getTransactionReceipt

Returns the receipt of a transaction by transaction hash.

eth_getCode

Returns the bytecode at a given contract address.

eth_getStorageAt

Returns the value from a storage position at a given address.

🔄 Transaction Methods

eth_call

Executes a message call immediately without creating a transaction.

eth_estimateGas

Estimates the gas required for a transaction.

eth_sendRawTransaction

Submits a pre-signed transaction for broadcast to the network.

eth_gasPrice

Returns the current price per gas in wei.

📊 Event and Log Methods

eth_getLogs

Returns an array of all logs matching a given filter object.

🌍 Network Methods

eth_chainId

Returns the chain ID of the current network.

net_version

Returns the current network ID.

net_listening

Returns true if client is actively listening for network connections.

net_peerCount

Returns the number of peers currently connected to the client.

Supported Networks

This server works with any EVM-compatible network:

• Ethereum: Mainnet, Sepolia, Goerli

• Polygon: Mainnet, Mumbai

• Arbitrum: One, Sepolia

• Optimism: Mainnet, Sepolia

• BNB Smart Chain: Mainnet, Testnet

• Avalanche: C-Chain

• Fantom: Opera

• And many more EVM-compatible chains

Installation

1. Clone this repository:

2. Install dependencies:

3. Set up environment variables:

Create a .env file in the project root:

RPC URL Examples

4. Build the project:

Usage

Adding to Claude Desktop

To use this EVM MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings.

1. Build the Server

First, build the server:

2. Configure Claude Desktop

1. Open Claude Desktop Settings:

   • On macOS: Cmd + , or go to Claude Desktop → Settings

   • On Windows: Ctrl + , or go to File → Settings

2. Add the MCP Server:

   • Click "Add server" or the "+" button

   • Fill in the configuration:

   Server Name: EVM MCP Server

   Command:

   node /path/to/your/evm-mcp/build/index.js

   Environment Variables:

   { "RPC_URL": "https://mainnet.infura.io/v3/YOUR_API_KEY", "CHAIN_ID": "1" }

3. Example Configuration:

   For Infura:

   { "RPC_URL": "https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID", "CHAIN_ID": "1" }

   For Alchemy:

   { "RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY", "CHAIN_ID": "1" }

   For Polygon:

   { "RPC_URL": "https://polygon-mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID", "CHAIN_ID": "137" }

   For Arbitrum:

   { "RPC_URL": "https://arbitrum-mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID", "CHAIN_ID": "42161" }

4. Save and Restart: Save the configuration and restart Claude Desktop.

3. Verify Connection

Once configured, you should see the EVM MCP Server available in Claude. You can test it by asking Claude to:

• "Get the latest Ethereum block number"

• "Check the balance of address 0x742d35Cc6634C0532925a3b8D6Ac6e2F0C4C9B7C"

• "Get the current gas price"

Running the Server Standalone

You can also run the server directly:

The server runs on stdio and can be connected to any MCP-compatible client.

Testing

Run the test suite:

Run tests in watch mode:

Example Queries

Here are some example queries you can make with this MCP server:

Get Latest Block Number

Get Account Balance

Get Transaction Information

Call a Smart Contract

Estimate Gas for a Transaction

Get Event Logs

Get Current Gas Price

Get Network Information

API Reference

Core EVM Methods

Network Methods

Web3 Methods

Data Format

• All hex values are returned in their original format

• Decimal conversions are provided for human readability

• Block numbers can be specified as hex strings or keywords: latest, earliest, pending

• Gas prices are displayed in both wei and gwei

• Timestamps are converted to ISO format when applicable

Error Handling

The server includes comprehensive error handling:

• Network errors are caught and reported with descriptive messages

• Invalid addresses or transaction hashes return appropriate error messages

• Rate limiting and API errors are handled gracefully

• Missing environment variables cause startup failures with clear messages

Configuration

Environment Variables

• RPC_URL (required): Any EVM-compatible RPC endpoint

• CHAIN_ID (optional): Chain ID for the network (defaults to 1)

Claude Desktop Configuration

When adding this MCP server to Claude Desktop, you'll need to configure it in the MCP settings. Here's a complete guide:

Step-by-Step Setup

1. Build the Server:

   npm run build

2. Open Claude Desktop Settings:

   • macOS: Press Cmd + , or go to Claude Desktop → Settings

   • Windows: Press Ctrl + , or go to File → Settings

3. Navigate to MCP Settings:

   • Look for "MCP" or "Model Context Protocol" in the settings menu

   • Click "Add server" or the "+" button

4. Configure the Server:

   Server Name: EVM MCP Server

   Command:

   node /full/path/to/your/evm-mcp/build/index.js

   Environment Variables (JSON format):

   { "RPC_URL": "https://mainnet.infura.io/v3/YOUR_API_KEY", "CHAIN_ID": "1" }

Network-Specific Configurations

Ethereum Mainnet (Infura):

Ethereum Mainnet (Alchemy):

Polygon Mainnet:

Arbitrum One:

Optimism Mainnet:

BNB Smart Chain:

Testing Your Configuration

After saving and restarting Claude Desktop, test the connection by asking Claude:

• "What's the latest Ethereum block number?"

• "Check the balance of address 0x742d35Cc6634C0532925a3b8D6Ac6e2F0C4C9B7C"

• "What's the current gas price?"

• "Get the chain ID of the current network"

If the server is working correctly, Claude should be able to execute these EVM RPC calls and return real blockchain data.

Troubleshooting Claude Desktop Setup

Common Issues and Solutions:

1. "Server not found" error:

   • Make sure you've built the server: npm run build

   • Verify the full path to build/index.js is correct

   • Check that Node.js is installed and accessible

2. "Environment variable not set" error:

   • Ensure the JSON format is correct (no trailing commas)

   • Make sure RPC_URL is set in the environment variables section

   • Verify your API key is valid and has sufficient quota

3. "Connection failed" error:

   • Test your RPC URL directly: curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' YOUR_RPC_URL

   • Check if your provider requires authentication

   • Verify the network is accessible from your location

4. Server appears but tools don't work:

   • Restart Claude Desktop after configuration changes

   • Check the server logs in Claude Desktop settings

   • Verify the server is running without errors

Supported Node Providers

• Infura: https://mainnet.infura.io/v3/YOUR_API_KEY

• Alchemy: https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

• QuickNode: https://YOUR_ENDPOINT.quiknode.pro/YOUR_TOKEN/

• Public RPCs: Various public endpoints (rate limited)

• Local Nodes: http://localhost:8545

• Custom Providers: Any JSON-RPC compatible endpoint

Dependencies

• @modelcontextprotocol/sdk - MCP SDK for server implementation

• ethers - Ethereum library for blockchain interaction

• zod - Schema validation for tool parameters

Development

Project Structure

Testing

The project uses Jest for unit testing. Tests are located in the test/ directory and can be run with:

Building

The project uses TypeScript and compiles to JavaScript in the build/ directory:

Use Cases

This MCP server is perfect for:

• Blockchain Analytics: Query transaction data, balances, and contract states

• 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 test smart contracts

• Monitoring: Watch for specific events and transaction patterns

• Research: Analyze blockchain data across multiple EVM networks

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

Support

For issues and questions:

1. Check the Issues page

2. Create a new issue with detailed information

3. Include your RPC URL configuration and error messages