EVM MCP Server

A comprehensive Model Context Protocol (MCP) server that provides blockchain services across multiple EVM-compatible networks. This server enables AI agents to interact with Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains with a unified interface.

📋 Contents

- Overview
- Features
- Supported Networks
- Prerequisites
- Installation
- Server Configuration
- Usage
- API Reference
- Tools
- Resources
- Security Considerations
- Project Structure
- Development
- License

🔭 Overview

The MCP EVM Server leverages the Model Context Protocol to provide blockchain services to AI agents. It supports a wide range of services including:

- Reading blockchain state (balances, transactions, blocks, etc.)
- Interacting with smart contracts
- Transferring tokens (native, ERC20, ERC721, ERC1155)
- Querying token metadata and balances
- Chain-specific services across 30+ EVM networks
- ENS name resolution for all address parameters (use human-readable names like 'vitalik.eth' instead of addresses)

All services are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use blockchain functionality. Every tool that accepts Ethereum addresses also supports ENS names, automatically resolving them to addresses behind the scenes.

✨ Features

Blockchain Data Access

- Multi-chain support for 30+ EVM-compatible networks
- Chain information including blockNumber, chainId, and RPCs
- Block data access by number, hash, or latest
- Transaction details and receipts with decoded logs
- Address balances for native tokens and all token standards
- ENS resolution for human-readable Ethereum addresses (use 'vitalik.eth' instead of '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

Token services

- ERC20 Tokens

- Get token metadata (name, symbol, decimals, supply)
- Check token balances
- Transfer tokens between addresses
- Approve spending allowances

- NFTs (ERC721)

- Get collection and token metadata
- Verify token ownership
- Transfer NFTs between addresses
- Retrieve token URIs and count holdings

- Multi-tokens (ERC1155)
- Get token balances and metadata
- Transfer tokens with quantity
- Access token URIs

Smart Contract Interactions

- Read contract state through view/pure functions
- Write services with private key signing
- Contract verification to distinguish from EOAs
- Event logs retrieval and filtering

Comprehensive Transaction Support

- Native token transfers across all supported networks
- Gas estimation for transaction planning
- Transaction status and receipt information
- Error handling with descriptive messages

🌐 Supported Networks

Mainnets

- Ethereum (ETH)
- Optimism (OP)
- Arbitrum (ARB)
- Arbitrum Nova
- Base
- Polygon (MATIC)
- Polygon zkEVM
- Avalanche (AVAX)
- Binance Smart Chain (BSC)
- zkSync Era
- Linea
- Celo
- Gnosis (xDai)
- Fantom (FTM)
- Filecoin (FIL)
- Moonbeam
- Moonriver
- Cronos
- Scroll
- Mantle
- Manta
- Blast
- Fraxtal
- Mode
- Metis
- Kroma
- Zora
- Aurora
- Canto

Testnets

- Sepolia
- Optimism Sepolia
- Arbitrum Sepolia
- Base Sepolia
- Polygon Amoy
- Avalanche Fuji
- BSC Testnet
- zkSync Sepolia
- Linea Sepolia
- Scroll Sepolia
- Mantle Sepolia
- Manta Sepolia
- Blast Sepolia
- Fraxtal Testnet
- Mode Testnet
- Metis Sepolia
- Kroma Sepolia
- Zora Sepolia
- Celo Alfajores
- Goerli
- Holesky

🛠️ Prerequisites

- Bun 1.0.0 or higher
- Node.js 18.0.0 or higher (if not using Bun)

📦 Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-evm-server.git
cd mcp-evm-server
Install dependencies with Bun
bun install
Or with npm
npm install

⚙️ Server Configuration

The server uses the following default configuration:

- Default Chain ID: 1 (Ethereum Mainnet)
- Server Port: 3001
- Server Host: 0.0.0.0 (accessible from any network interface)

These values are hardcoded in the application. If you need to modify them, you can edit the following files:

- For chain configuration: src/core/chains.ts
- For server configuration: src/server/http-server.ts

🚀 Usage

Using npx (No Installation Required)

You can run the MCP EVM Server directly without installation using npx:

# Run the server in stdio mode (for CLI tools)
npx @mcpdotdirect/evm-mcp-server
Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/evm-mcp-server --http

Running the Server Locally

Start the server using stdio (for embedding in CLI tools):

# Start the stdio server
bun start
Development mode with auto-reload
bun dev

Or start the HTTP server with SSE for web applications:

# Start the HTTP server
bun start:http
Development mode with auto-reload
bun dev:http

Connecting to the Server

Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the MCP Inspector.

Connecting from Cursor

To connect to the MCP server from Cursor:

1. Open Cursor and go to Settings (gear icon in the bottom left)
2. Click on "Features" in the left sidebar
3. Scroll down to "MCP Servers" section
4. Click "Add new MCP server"
5. Enter the following details:

- Server name: evm-mcp-server
- Type: command
- Command: npx @mcpdotdirect/evm-mcp-server

6. Click "Save"

Once connected, you can use the MCP server's capabilities directly within Cursor. The server will appear in the MCP Servers list and can be enabled/disabled as needed.

Using mcp.json with Cursor

For a more portable configuration that you can share with your team or use across projects, you can create an .cursor/mcp.json file in your project's root directory:

{
  "mcpServers": {
    "evm-mcp-server": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server"]
    },
    "evm-mcp-http": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"]
    }
  }
}

Place this file in your project's .cursor directory (create it if it doesn't exist), and Cursor will automatically detect and use these MCP server configurations when working in that project. This approach makes it easy to:

1. Share MCP configurations with your team
2. Version control your MCP setup
3. Use different server configurations for different projects

Example: HTTP Mode with SSE

If you're developing a web application and want to connect to the HTTP server with Server-Sent Events (SSE), you can use this configuration:

{
  "mcpServers": {
    "evm-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

This connects directly to the HTTP server's SSE endpoint, which is useful for:

- Web applications that need to connect to the MCP server from the browser
- Environments where running local commands isn't ideal
- Sharing a single MCP server instance among multiple users or applications

To use this configuration:

1. Create a .cursor directory in your project root if it doesn't exist
2. Save the above JSON as mcp.json in the .cursor directory
3. Restart Cursor or open your project
4. Cursor will detect the configuration and offer to enable the server(s)

Example: Using the MCP Server in Cursor

…