📌Overview

Purpose: The EVM MCP Server aims to provide a comprehensive blockchain service framework that allows AI agents to interact seamlessly with multiple EVM-compatible networks.

Overview: The MCP EVM Server utilizes the Model Context Protocol (MCP) to facilitate blockchain services across various EVM networks. It simplifies access to blockchain data and interactions, enabling functionalities like reading blockchain states, managing tokens, and engaging with smart contracts through a consistent interface.

Key Features:

Multi-chain Support: Offers services across 30+ EVM-compatible networks, ensuring broad compatibility.
Token Services: Facilitates complete ERC20, ERC721, and ERC1155 token management, including balance checks and transfers, with automatic ENS name resolution for user-friendly interactions.

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.

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

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
Flow
Lumia

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
Flow Testnet
Lumia Testnet

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/mcpdotdirect/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. To modify them, edit the following files:

Chain configuration: src/core/chains.ts
Server configuration: src/server/http-server.ts

Usage

Using npx (No Installation Required)

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:

Open Cursor and go to Settings (gear icon in the bottom left).
Click on Features in the left sidebar.
Scroll down to "MCP Servers" section.
Click "Add new MCP server".
Enter the following details:
- Server name: evm-mcp-server
- Type: command
- Command: npx @mcpdotdirect/evm-mcp-server
Click "Save".

Once connected, you can use the MCP server's capabilities directly within Cursor.

Using mcp.json with Cursor

Create an .cursor/mcp.json file in your project's root directory to share configurations:

{
  "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 .cursor directory. Cursor will detect and use these MCP server configurations automatically.

Example: HTTP Mode with SSE

Configure connection to the HTTP server with Server-Sent Events (SSE):

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

This setup is useful for:

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

Example: Using the MCP Server in Cursor

Example workflow:

Create a new JavaScript/TypeScript file:

// blockchain-example.js
async function main() {
  try {
    // Get ETH balance for an address using ENS
    console.log("Getting ETH balance for vitalik.eth...");
    
    // You can instruct Cursor to:
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"
    
    // Cursor uses the MCP server to execute these operations 
    // without additional code.
    
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

With the file open, you can ask Cursor to execute blockchain-related tasks naturally.

Connecting using Claude CLI

Connect to the MCP server with Claude CLI using:

# Add the MCP server
claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server

# Start Claude with the MCP server enabled
claude

Example: Getting a Token Balance with ENS

const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
  ownerAddress: "vitalik.eth",
  network: "ethereum"
});

console.log(result);

Example: Resolving an ENS Name

const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve-ens", {
  ensName: "vitalik.eth",
  network: "ethereum"
});

console.log(result);

API Reference

Tools

The server provides MCP tools for agents. All tools accepting address parameters support both Ethereum addresses and ENS names.

Token Services

Tool Name	Description	Key Parameters
`get-token-info`	Get ERC20 token metadata	`tokenAddress` (address/ENS), `network`
`get-token-balance`	Check ERC20 token balance	`tokenAddress`, `ownerAddress`, `network`
`transfer-token`	Transfer ERC20 tokens	`privateKey`, `tokenAddress`, `toAddress`, `amount`, `network`
`approve-token-spending`	Approve token allowances	`privateKey`, `tokenAddress`, `spenderAddress`, `amount`, `network`
`get-nft-info`	Get NFT metadata	`tokenAddress`, `tokenId`, `network`
`check-nft-ownership`	Verify NFT ownership	`tokenAddress`, `tokenId`, `ownerAddress`, `network`
`transfer-nft`	Transfer an NFT	`privateKey`, `tokenAddress`, `tokenId`, `toAddress`, `network`
`get-nft-balance`	Count NFTs owned	`tokenAddress`, `ownerAddress`, `network`
`get-erc1155-token-uri`	Get ERC1155 metadata	`tokenAddress`, `tokenId`, `network`
`get-erc1155-balance`	Check ERC1155 balance	`tokenAddress`, `tokenId`, `ownerAddress`, `network`
`transfer-erc1155`	Transfer ERC1155 tokens	`privateKey`, `tokenAddress`, `tokenId`, `amount`, `toAddress`, `network`

Blockchain Services

Tool Name	Description	Key Parameters
`get-chain-info`	Get network information	`network`
`get-balance`	Get native token balance	`address`, `network`
`transfer-eth`	Send native tokens	`privateKey`, `to`, `amount`, `network`
`get-transaction`	Get transaction details	`txHash`, `network`
`read-contract`	Read smart contract state	`contractAddress`, `abi`, `functionName`, `args`, `network`
`write-contract`	Write to smart contract	`contractAddress`, `abi`, `functionName`, `args`, `privateKey`, `network`
`is-contract`	Check if address is contract	`address`, `network`
`resolve-ens`	Resolve ENS to address	`ensName`, `network`

Resources

The server exposes blockchain data through MCP resource URIs. All resource URIs accepting addresses support ENS names.

Blockchain Resources

Resource URI Pattern	Description
`evm://{network}/chain`	Chain information for a network
`evm://chain`	Ethereum mainnet chain information
`evm://{network}/block/{blockNumber}`	Block data by number
`evm://{network}/block/latest`	Latest block data
`evm://{network}/address/{address}/balance`	Native token balance
`evm://{network}/tx/{txHash}`	Transaction details
`evm://{network}/tx/{txHash}/receipt`	Transaction receipt with logs

Token Resources

Resource URI Pattern	Description
`evm://{network}/token/{tokenAddress}`	ERC20 token information
`evm://{network}/token/{tokenAddress}/balanceOf/{address}`	ERC20 token balance
`evm://{network}/nft/{tokenAddress}/{tokenId}`	NFT (ERC721) information
`evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}`	NFT ownership verification
`evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri`	ERC1155 token URI
`evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}`	ERC1155 token balance

Security Considerations

Private keys are used only for transaction signing and are never stored by the server
Implement additional authentication for production
Use HTTPS for the HTTP server in production
Implement rate limiting to prevent abuse
For high-value services, consider adding confirmation steps

Project Structure

mcp-evm-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Operation exports
│   │       ├── balance.ts      # Balance services
│   │       ├── transfer.ts     # Token transfer services
│   │       ├── utils.ts        # Utility functions
│   │       ├── tokens.ts       # Token metadata services
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── transactions.ts # Transaction services
│   │       ├── blocks.ts       # Block services
│   │       └── clients.ts      # RPC client utilities
├── package.json
├── tsconfig.json
└── README.md

Development

To modify or extend the server:

Add new services under src/core/services/
Register new tools in src/core/tools.ts
Register new resources in src/core/resources.ts
Add new network support in src/core/chains.ts
Change server configuration in src/server/http-server.ts

License

This project is licensed under the terms of the MIT License.

evm-mcp-server

📌Overview

EVM MCP Server

Contents

Overview

Features

Blockchain Data Access

Token Services

Smart Contract Interactions

Comprehensive Transaction Support

Supported Networks

Mainnets

Testnets

Prerequisites

Installation

Server Configuration

Usage

Using npx (No Installation Required)

Running the Server Locally

Connecting to the Server

Connecting from Cursor

Using mcp.json with Cursor

Example: HTTP Mode with SSE

Example: Using the MCP Server in Cursor

Connecting using Claude CLI

Example: Getting a Token Balance with ENS

Example: Resolving an ENS Name

API Reference

Tools

Token Services

Blockchain Services

Resources

Blockchain Resources

Token Resources

Security Considerations

Project Structure

Development

License