EVM MCP Server

📋 Contents

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

🔭 Overview

• 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)

✨ 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
• 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

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

• For chain configuration:

  src/core/chains.ts

• For server configuration:

  src/server/http-server.ts

🚀 Usage

Using npx (No Installation Required)

# 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 stdio server
bun start

# Development mode with auto-reload
bun dev

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

Connecting to the Server

Connecting 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"

Using mcp.json with Cursor

.cursor/mcp.json

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

.cursor

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

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

• 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

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

mcp.json

1. Create a new JavaScript/TypeScript file in your project:

// blockchain-example.js
async function main() {
  try {
    // Get ETH balance for an address using ENS
    console.log("Getting ETH balance for vitalik.eth...");
    
    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"
    
    // Cursor will use the MCP server to execute these operations 
    // without requiring any additional code from you
    
    // This is the power of the MCP integration - your AI assistant
    // can directly interact with blockchain data and operations
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

1. With the file open in Cursor, you can ask Cursor to:
   • "Check the current ETH balance of vitalik.eth"
   • "Look up the price of USDC on Ethereum"
   • "Show me the latest block on Optimism"
   • "Check if 0x1234... is a contract address"
2. Cursor will use the MCP server to execute these operations and return the results directly in your conversation.

Connecting using Claude CLI

# 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

// Example of using the MCP client to check a token balance using ENS
const mcp = new McpClient("http://localhost:3000");

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

console.log(result);
// {
//   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum",
//   raw: "1000000000",
//   formatted: "1000",
//   symbol: "USDC",
//   decimals: 6
// }

Example: Resolving an ENS Name

// Example of using the MCP client to resolve an ENS name to an address
const mcp = new McpClient("http://localhost:3000");

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

console.log(result);
// {
//   ensName: "vitalik.eth",
//   normalizedName: "vitalik.eth",
//   resolvedAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum"
// }

📚 API Reference

Tools

Token services

get-token-info

tokenAddress

network

get-token-balance

tokenAddress

ownerAddress

network

transfer-token

privateKey

tokenAddress

toAddress

amount

network

approve-token-spending

privateKey

tokenAddress

spenderAddress

amount

network

get-nft-info

tokenAddress

tokenId

network

check-nft-ownership

tokenAddress

tokenId

ownerAddress

network

transfer-nft

privateKey

tokenAddress

tokenId

toAddress

network

get-nft-balance

tokenAddress

ownerAddress

network

get-erc1155-token-uri

tokenAddress

tokenId

network

get-erc1155-balance

tokenAddress

tokenId

ownerAddress

network

transfer-erc1155

privateKey

tokenAddress

tokenId

amount

toAddress

network

Blockchain services

get-chain-info

network

get-balance

address

network

transfer-eth

privateKey

to

amount

network

get-transaction

txHash

network

read-contract

contractAddress

abi

functionName

args

network

write-contract

contractAddress

abi

functionName

args

privateKey

network

is-contract

address

network

resolve-ens

ensName

network

Resources

Blockchain Resources

evm://{network}/chain

evm://chain

evm://{network}/block/{blockNumber}

evm://{network}/block/latest

evm://{network}/address/{address}/balance

evm://{network}/tx/{txHash}

evm://{network}/tx/{txHash}/receipt

Token Resources

evm://{network}/token/{tokenAddress}

evm://{network}/token/{tokenAddress}/balanceOf/{address}

evm://{network}/nft/{tokenAddress}/{tokenId}

evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}

evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri

evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}

🔒 Security Considerations

• Private keys are used only for transaction signing and are never stored by the server
• Consider implementing additional authentication mechanisms for production use
• Use HTTPS for the HTTP server in production environments
• 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

1. Add new services in the appropriate file under

   src/core/services/

2. Register new tools in

   src/core/tools.ts

3. Register new resources in

   src/core/resources.ts

4. Add new network support in

   src/core/chains.ts

5. To change server configuration, edit the hardcoded values in

   src/server/http-server.ts

📄 License