A comprehensive Model Context Protocol (MCP) server that provides blockchain services across 60+ 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 through 22 tools and 10 AI-guided prompts. - Supported Networks - Prerequisites - Installation - Configuration - Environment Variables
Add this skill
npx mdskills install mcpdotdirect/evm-mcp-serverComprehensive blockchain MCP server with 22 tools across 60+ EVM networks and ENS support
1# EVM MCP Server23456789A comprehensive Model Context Protocol (MCP) server that provides blockchain services across 60+ 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 through 22 tools and 10 AI-guided prompts.1011## 📋 Contents1213- [Overview](#overview)14- [Features](#features)15- [Supported Networks](#supported-networks)16- [Prerequisites](#prerequisites)17- [Installation](#installation)18- [Configuration](#configuration)19 - [Environment Variables](#environment-variables)20 - [Server Configuration](#server-configuration)21- [Usage](#usage)22- [API Reference](#api-reference)23 - [Tools](#tools)24 - [Prompts](#prompts)25 - [Resources](#resources)26- [Security Considerations](#security-considerations)27- [Project Structure](#project-structure)28- [Development](#development)29- [License](#license)3031## 🔭 Overview3233The MCP EVM Server leverages the Model Context Protocol to provide blockchain services to AI agents. It supports a wide range of services including:3435- Reading blockchain state (balances, transactions, blocks, etc.)36- Interacting with smart contracts with **automatic ABI fetching** from block explorers37- Transferring tokens (native, ERC20, ERC721, ERC1155)38- Querying token metadata and balances39- Chain-specific services across 60+ EVM networks (34 mainnets + 26 testnets)40- **ENS name resolution** for all address parameters (use human-readable names like 'vitalik.eth' instead of addresses)41- **AI-friendly prompts** that guide agents through complex workflows4243All services are exposed through a consistent interface of MCP tools, resources, and prompts, 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. The server includes intelligent ABI fetching, eliminating the need to know contract ABIs in advance.4445## ✨ Features4647### Blockchain Data Access4849- **Multi-chain support** for 60+ EVM-compatible networks (34 mainnets + 26 testnets)50- **Chain information** including blockNumber, chainId, and RPCs51- **Block data** access by number, hash, or latest52- **Transaction details** and receipts with decoded logs53- **Address balances** for native tokens and all token standards54- **ENS resolution** for human-readable Ethereum addresses (use 'vitalik.eth' instead of '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')5556### Token services5758- **ERC20 Tokens**5960 - Get token metadata (name, symbol, decimals, supply)61 - Check token balances62 - Transfer tokens between addresses63 - Approve spending allowances6465- **NFTs (ERC721)**6667 - Get collection and token metadata68 - Verify token ownership69 - Transfer NFTs between addresses70 - Retrieve token URIs and count holdings7172- **Multi-tokens (ERC1155)**73 - Get token balances and metadata74 - Transfer tokens with quantity75 - Access token URIs7677### Smart Contract Interactions7879- **Read contract state** through view/pure functions80- **Write to contracts** - Execute any state-changing function with automatic ABI fetching81- **Contract verification** to distinguish from EOAs82- **Event logs** retrieval and filtering83- **Automatic ABI fetching** from Etherscan v2 API across all 60+ networks (no need to know ABIs in advance)84- **ABI parsing and validation** with function discovery8586### Comprehensive Transaction Support8788- **Flexible Wallet Support** - Configure with Private Key or Mnemonic (BIP-39) with HD path support89- **Native token transfers** across all supported networks90- **Gas estimation** for transaction planning91- **Transaction status** and receipt information92- **Error handling** with descriptive messages9394### Message Signing Capabilities9596- **Personal Message Signing** - Sign arbitrary messages for authentication and verification97- **EIP-712 Typed Data Signing** - Sign structured data for gasless transactions and meta-transactions98- **SIWE Support** - Enable Sign-In With Ethereum authentication flows99- **Permit Signatures** - Create off-chain approvals for gasless token operations100- **Meta-Transaction Support** - Sign transaction data for relay services and gasless transfers101102### AI-Guided Workflows (Prompts)103104- **Transaction preparation** - Guidance for planning and executing transfers105- **Wallet analysis** - Tools for analyzing wallet activity and holdings106- **Smart contract exploration** - Interactive ABI fetching and contract analysis107- **Contract interaction** - Safe execution of write operations on smart contracts108- **Network information** - Learning about EVM networks and comparisons109- **Approval auditing** - Reviewing and managing token approvals110- **Error diagnosis** - Troubleshooting transaction failures111112## 🌐 Supported Networks113114### Mainnets115116- Ethereum (ETH)117- Optimism (OP)118- Arbitrum (ARB)119- Arbitrum Nova120- Base121- Polygon (MATIC)122- Polygon zkEVM123- Avalanche (AVAX)124- Binance Smart Chain (BSC)125- zkSync Era126- Linea127- Celo128- Gnosis (xDai)129- Fantom (FTM)130- Filecoin (FIL)131- Moonbeam132- Moonriver133- Cronos134- Scroll135- Mantle136- Manta137- Blast138- Fraxtal139- Mode140- Metis141- Kroma142- Zora143- Aurora144- Canto145- Flow146- Lumia147148### Testnets149150- Sepolia151- Optimism Sepolia152- Arbitrum Sepolia153- Base Sepolia154- Polygon Amoy155- Avalanche Fuji156- BSC Testnet157- zkSync Sepolia158- Linea Sepolia159- Scroll Sepolia160- Mantle Sepolia161- Manta Sepolia162- Blast Sepolia163- Fraxtal Testnet164- Mode Testnet165- Metis Sepolia166- Kroma Sepolia167- Zora Sepolia168- Celo Alfajores169- Goerli170- Holesky171- Flow Testnet172- Filecoin Calibration173- Lumia Testnet174175## 🛠️ Prerequisites176177- [Bun](https://bun.sh/) 1.0.0 or higher (recommended)178- Node.js 20.0.0 or higher (if not using Bun)179- Optional: [Etherscan API key](https://etherscan.io/apis) for ABI fetching180181## 📦 Installation182183```bash184# Clone the repository185git clone https://github.com/mcpdotdirect/mcp-evm-server.git186cd mcp-evm-server187188# Install dependencies with Bun189bun install190191# Or with npm192npm install193```194195## ⚙️ Configuration196197### Environment Variables198199The server uses the following environment variables. For write operations and ABI fetching, you must configure these variables:200201#### Wallet Configuration (For Write Operations)202203You can configure your wallet using **either** a private key or a mnemonic phrase:204205**Option 1: Private Key**206207```bash208export EVM_PRIVATE_KEY="0x..." # Your private key in hex format (with or without 0x prefix)209```210211**Option 2: Mnemonic Phrase (Recommended for HD Wallets)**212213```bash214export EVM_MNEMONIC="word1 word2 word3 ... word12" # Your 12 or 24 word BIP-39 mnemonic215export EVM_ACCOUNT_INDEX="0" # Optional: Account index for HD wallet derivation (default: 0)216```217218The mnemonic option supports hierarchical deterministic (HD) wallet derivation:219220- Uses BIP-39 standard mnemonic phrases (12 or 24 words)221- Supports BIP-44 derivation path: `m/44'/60'/0'/0/{accountIndex}`222- `EVM_ACCOUNT_INDEX` allows you to derive different accounts from the same mnemonic223- Default account index is 0 (first account)224225**Wallet is used for:**226227- Transferring native tokens (`transfer_native` tool)228- Transferring ERC20 tokens (`transfer_erc20` tool)229- Approving token spending (`approve_token_spending` tool)230- Writing to smart contracts (`write_contract` tool)231- Signing messages for authentication (`sign_message` tool)232- Signing structured data for gasless transactions (`sign_typed_data` tool)233234⚠️ **Security**:235236- Never commit your private key or mnemonic to version control237- Use environment variables or a secure key management system238- Store mnemonics securely - they provide access to all derived accounts239- Consider using different account indices for different purposes240241#### API Keys (For ABI Fetching)242243```bash244export ETHERSCAN_API_KEY="your-api-key-here"245```246247This API key is optional but required for:248249- Automatic ABI fetching from block explorers (`get_contract_abi` tool)250- Auto-fetching ABIs when reading contracts (`read_contract` tool with `abiJson` parameter)251- The `fetch_and_analyze_abi` prompt252253Get your free API key from:254255- [Etherscan](https://etherscan.io/apis) - For Ethereum and compatible chains256- The same key works across all 60+ EVM networks via the Etherscan v2 API257258### Server Configuration259260The server uses the following default configuration:261262- **Default Chain ID**: 1 (Ethereum Mainnet)263- **Server Port**: 3001264- **Server Host**: 0.0.0.0 (accessible from any network interface)265266These values are hardcoded in the application. If you need to modify them, you can edit the following files:267268- For chain configuration: `src/core/chains.ts`269- For server configuration: `src/server/http-server.ts`270271## 🚀 Usage272273### Using npx (No Installation Required)274275You can run the MCP EVM Server directly without installation using npx:276277```bash278# Run the server in stdio mode (for CLI tools)279npx @mcpdotdirect/evm-mcp-server280281# Run the server in HTTP mode (for web applications)282npx @mcpdotdirect/evm-mcp-server --http283```284285### Running the Server Locally286287Start the server using stdio (for embedding in CLI tools):288289```bash290# Start the stdio server291bun start292293# Development mode with auto-reload294bun dev295```296297Or start the HTTP server with SSE for web applications:298299```bash300# Start the HTTP server301bun start:http302303# Development mode with auto-reload304bun dev:http305```306307### Connecting to the Server308309Connect to this MCP server using any MCP-compatible client. For testing and debugging, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).310311### Connecting from Cursor312313To connect to the MCP server from Cursor:3143151. Open Cursor and go to Settings (gear icon in the bottom left)3162. Click on "Features" in the left sidebar3173. Scroll down to "MCP Servers" section3184. Click "Add new MCP server"3195. Enter the following details:320321 - Server name: `evm-mcp-server`322 - Type: `command`323 - Command: `npx @mcpdotdirect/evm-mcp-server`3243256. Click "Save"326327Once 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.328329### Using mcp.json with Cursor330331For 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:332333```json334{335 "mcpServers": {336 "evm-mcp-server": {337 "command": "npx",338 "args": ["-y", "@mcpdotdirect/evm-mcp-server"]339 },340 "evm-mcp-http": {341 "command": "npx",342 "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"]343 }344 }345}346```347348Place 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:3493501. Share MCP configurations with your team3512. Version control your MCP setup3523. Use different server configurations for different projects353354### Example: HTTP Mode with SSE355356If you're developing a web application and want to connect to the HTTP server with Server-Sent Events (SSE), you can use this configuration:357358```json359{360 "mcpServers": {361 "evm-mcp-sse": {362 "url": "http://localhost:3001/sse"363 }364 }365}366```367368This connects directly to the HTTP server's SSE endpoint, which is useful for:369370- Web applications that need to connect to the MCP server from the browser371- Environments where running local commands isn't ideal372- Sharing a single MCP server instance among multiple users or applications373374To use this configuration:3753761. Create a `.cursor` directory in your project root if it doesn't exist3772. Save the above JSON as `mcp.json` in the `.cursor` directory3783. Restart Cursor or open your project3794. Cursor will detect the configuration and offer to enable the server(s)380381### Example: Using the MCP Server in Cursor382383After configuring the MCP server with `mcp.json`, you can easily use it in Cursor. Here's an example workflow:3843851. Create a new JavaScript/TypeScript file in your project:386387```javascript388// blockchain-example.js389async function main() {390 try {391 // Get ETH balance for an address using ENS392 console.log("Getting ETH balance for vitalik.eth...");393394 // When using with Cursor, you can simply ask Cursor to:395 // "Check the ETH balance of vitalik.eth on mainnet"396 // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"397398 // Cursor will use the MCP server to execute these operations399 // without requiring any additional code from you400401 // This is the power of the MCP integration - your AI assistant402 // can directly interact with blockchain data and operations403 } catch (error) {404 console.error("Error:", error.message);405 }406}407408main();409```4104112. With the file open in Cursor, you can ask Cursor to:412413 - "Check the current ETH balance of vitalik.eth"414 - "Look up the price of USDC on Ethereum"415 - "Show me the latest block on Optimism"416 - "Check if 0x1234... is a contract address"4174183. Cursor will use the MCP server to execute these operations and return the results directly in your conversation.419420The MCP server handles all the blockchain communication while allowing Cursor to understand and execute blockchain-related tasks through natural language.421422### Connecting using Claude CLI423424If you're using Claude CLI, you can connect to the MCP server with just two commands:425426```bash427# Add the MCP server428claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server429430# Start Claude with the MCP server enabled431claude432```433434### Example: Getting a Token Balance with ENS435436```javascript437// Example of using the MCP client to check a token balance using ENS438const mcp = new McpClient("http://localhost:3000");439440const result = await mcp.invokeTool("get-token-balance", {441 tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum442 ownerAddress: "vitalik.eth", // ENS name instead of address443 network: "ethereum",444});445446console.log(result);447// {448// tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",449// owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",450// network: "ethereum",451// raw: "1000000000",452// formatted: "1000",453// symbol: "USDC",454// decimals: 6455// }456```457458### Example: Resolving an ENS Name459460```javascript461// Example of using the MCP client to resolve an ENS name to an address462const mcp = new McpClient("http://localhost:3000");463464const result = await mcp.invokeTool("resolve-ens", {465 ensName: "vitalik.eth",466 network: "ethereum",467});468469console.log(result);470// {471// ensName: "vitalik.eth",472// normalizedName: "vitalik.eth",473// resolvedAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",474// network: "ethereum"475// }476```477478### Example: Batch Multiple Calls with Multicall479480```javascript481// Example of using multicall to batch multiple contract reads in a single RPC call482const mcp = new McpClient("http://localhost:3000");483484const result = await mcp.invokeTool("multicall", {485 network: "ethereum",486 calls: [487 {488 contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC489 functionName: "balanceOf",490 args: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],491 },492 {493 contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC494 functionName: "symbol",495 },496 {497 contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC498 functionName: "decimals",499 },500 ],501});502503console.log(result);504// {505// network: "ethereum",506// totalCalls: 3,507// successfulCalls: 3,508// failedCalls: 0,509// results: [510// { contractAddress: "0xA0b...", functionName: "balanceOf", result: "1000000000", status: "success" },511// { contractAddress: "0xA0b...", functionName: "symbol", result: "USDC", status: "success" },512// { contractAddress: "0xA0b...", functionName: "decimals", result: "6", status: "success" }513// ]514// }515```516517## 📚 API Reference518519### Tools520521The server provides 25 focused MCP tools for agents. **All tools that accept address parameters support both Ethereum addresses and ENS names.**522523#### Wallet Information524525| Tool Name | Description | Key Parameters |526| -------------------- | --------------------------------------------------------------- | -------------- |527| `get_wallet_address` | Get the address of the configured wallet (from EVM_PRIVATE_KEY) | none |528529#### Network Information530531| Tool Name | Description | Key Parameters |532| ------------------------ | ----------------------------------- | -------------- |533| `get_chain_info` | Get network information | `network` |534| `get_supported_networks` | List all supported EVM networks | none |535| `get_gas_price` | Get current gas prices on a network | `network` |536537#### ENS Services538539| Tool Name | Description | Key Parameters |540| -------------------- | ---------------------------------- | -------------------- |541| `resolve_ens_name` | Resolve ENS name to address | `ensName`, `network` |542| `lookup_ens_address` | Reverse lookup address to ENS name | `address`, `network` |543544#### Block & Transaction Information545546| Tool Name | Description | Key Parameters |547| ------------------------- | --------------------------------- | --------------------------------------- |548| `get_block` | Get block data | `blockNumber` or `blockHash`, `network` |549| `get_latest_block` | Get latest block data | `network` |550| `get_transaction` | Get transaction details | `txHash`, `network` |551| `get_transaction_receipt` | Get transaction receipt with logs | `txHash`, `network` |552| `wait_for_transaction` | Wait for transaction confirmation | `txHash`, `confirmations`, `network` |553554#### Balance & Token Information555556| Tool Name | Description | Key Parameters |557| ------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |558| `get_balance` | Get native token balance | `address` (address/ENS), `network` |559| `get_token_balance` | Check ERC20 token balance | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `network` |560| `get_allowance` | Check token spending allowance | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `spenderAddress` (address/ENS), `network` |561562#### Smart Contract Interactions563564| Tool Name | Description | Key Parameters |565| ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |566| `get_contract_abi` | Fetch contract ABI from block explorer (60+ networks) | `contractAddress` (address/ENS), `network` |567| `read_contract` | Read smart contract state (auto-fetches ABI if needed) | `contractAddress`, `functionName`, `args[]`, `abiJson` (optional), `network` |568| `write_contract` | Execute state-changing functions (auto-fetches ABI if needed) | `contractAddress`, `functionName`, `args[]`, `value` (optional), `abiJson` (optional), `network` |569| `multicall` | Batch multiple read calls into a single RPC request (uses Multicall3) | `calls[]` (array of contract calls), `allowFailure` (optional), `network` |570571#### Token Transfers572573| Tool Name | Description | Key Parameters |574| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------- |575| `transfer_native` | Send native tokens (ETH, etc.) | `to` (address/ENS), `amount`, `network` |576| `transfer_erc20` | Transfer ERC20 tokens | `tokenAddress` (address/ENS), `to` (address/ENS), `amount`, `network` |577| `approve_token_spending` | Approve token allowances | `tokenAddress` (address/ENS), `spenderAddress` (address/ENS), `amount`, `network` |578579#### NFT Services580581| Tool Name | Description | Key Parameters |582| --------------------- | ------------------------- | -------------------------------------------------------------------------------- |583| `get_nft_info` | Get NFT (ERC721) metadata | `tokenAddress` (address/ENS), `tokenId`, `network` |584| `get_erc1155_balance` | Check ERC1155 balance | `tokenAddress` (address/ENS), `tokenId`, `ownerAddress` (address/ENS), `network` |585586#### Message Signing587588| Tool Name | Description | Key Parameters |589| ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |590| `sign_message` | Sign arbitrary messages for authentication and verification (SIWE, off-chain signatures) | `message` |591| `sign_typed_data` | Sign EIP-712 structured data for gasless transactions, permits, and meta-transactions | `domainJson`, `typesJson`, `primaryType`, `messageJson` |592593### Resources594595The server exposes blockchain data through the following MCP resource URIs. All resource URIs that accept addresses also support ENS names, which are automatically resolved to addresses.596597#### Blockchain Resources598599| Resource URI Pattern | Description |600| ------------------------------------------- | ---------------------------------------- |601| `evm://{network}/chain` | Chain information for a specific network |602| `evm://chain` | Ethereum mainnet chain information |603| `evm://{network}/block/{blockNumber}` | Block data by number |604| `evm://{network}/block/latest` | Latest block data |605| `evm://{network}/address/{address}/balance` | Native token balance |606| `evm://{network}/tx/{txHash}` | Transaction details |607| `evm://{network}/tx/{txHash}/receipt` | Transaction receipt with logs |608609#### Token Resources610611| Resource URI Pattern | Description |612| ---------------------------------------------------------------------- | ------------------------------ |613| `evm://{network}/token/{tokenAddress}` | ERC20 token information |614| `evm://{network}/token/{tokenAddress}/balanceOf/{address}` | ERC20 token balance |615| `evm://{network}/nft/{tokenAddress}/{tokenId}` | NFT (ERC721) token information |616| `evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}` | NFT ownership verification |617| `evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri` | ERC1155 token URI |618| `evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}` | ERC1155 token balance |619620## 🔒 Security Considerations621622- **Private keys** are used only for transaction signing and are never stored by the server623- Consider implementing additional authentication mechanisms for production use624- Use HTTPS for the HTTP server in production environments625- Implement rate limiting to prevent abuse626- For high-value services, consider adding confirmation steps627628## 📁 Project Structure629630```631mcp-evm-server/632├── src/633│ ├── index.ts # Main stdio server entry point634│ ├── server/ # Server-related files635│ │ ├── http-server.ts # HTTP server with SSE636│ │ └── server.ts # General server setup637│ ├── core/638│ │ ├── chains.ts # Chain definitions and utilities639│ │ ├── resources.ts # MCP resources implementation640│ │ ├── tools.ts # MCP tools implementation641│ │ ├── prompts.ts # MCP prompts implementation642│ │ └── services/ # Core blockchain services643│ │ ├── index.ts # Operation exports644│ │ ├── balance.ts # Balance services645│ │ ├── transfer.ts # Token transfer services646│ │ ├── utils.ts # Utility functions647│ │ ├── tokens.ts # Token metadata services648│ │ ├── contracts.ts # Contract interactions649│ │ ├── transactions.ts # Transaction services650│ │ └── blocks.ts # Block services651│ │ └── clients.ts # RPC client utilities652├── package.json653├── tsconfig.json654└── README.md655```656657## 🛠️ Development658659To modify or extend the server:6606611. Add new services in the appropriate file under `src/core/services/`6622. Register new tools in `src/core/tools.ts`6633. Register new resources in `src/core/resources.ts`6644. Add new network support in `src/core/chains.ts`6655. To change server configuration, edit the hardcoded values in `src/server/http-server.ts`666667## 📄 License668669This project is licensed under the terms of the [MIT License](./LICENSE).670
Full transparency — inspect the skill content before installing.