Ethereum JSON-RPC MCP

Introduction

This project provides a Node.js-based proxy server designed to expose an Ethereum JSON-RPC endpoint as a suite of MCP tools. The primary objective is to offer an accessible MCP interface, featuring robust schema validation, clear and concise responses, and a passthrough utility (eth_callRaw) for methods not explicitly defined.

Features

• MCP tool registration, incorporating Zod validation and user-friendly aliases.
• Support for prevalent Ethereum RPC methods, augmented by a selection of administrative, debugging, and transaction pool utilities.
• Automatic conversion of hexadecimal values to decimal for block numbers, balances, and gas prices.
• Secure-by-default transaction broadcasting, with an option to enable raw transaction submission via ALLOW_SEND_RAW_TX=1.
• Dedicated endpoints for health monitoring and service discovery (/, /health, /mcp).
• JSON-RPC passthrough functionality through eth_callRaw, adhering to established raw transaction submission safety protocols..

Quickstart

1. Clone and install:

   git clone https://github.com/John0n1/ethereum-mcp.git
   cd ethereum-mcp
   npm install
   

2. Copy the env template and edit GETH_URL:

   # PowerShell
   Copy-Item example.env .env
   
   # macOS/Linux
   cp example.env .env
   

3. Start the server:

   npm start
   

4. Verify connectivity:

   curl http://localhost:3000/health?upstream=1
   

5. List tools:

   curl -s http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

6. Call a tool:

   curl -s http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"getBlockNumber","arguments":{}}}'
   

Configuration

Create a .env file in the root directory:

GETH_URL=http://localhost:8545  # URL to your Geth/Nethermind node's JSON-RPC endpoint
PORT=3000                       # Optional: Server port (default: 3000)
ALLOW_SEND_RAW_TX=0             # Optional: Set to 1/true to enable transaction broadcasting

• GETH_URL is required.
• Some admin/debug methods may require Geth flags such as --http.api or --ws.api.

Usage

• Root: GET / returns basic metadata and endpoints.
• Health: GET /health (add ?upstream=1 to verify Geth).
• MCP: POST /mcp supports initialize, tools/list, and tools/call.
• Simple REST: GET /blockNumber returns the current block number in hex and decimal.

MCP Client Config

If your MCP client uses a config file, point it to the server:

{
  "ethereum-mcp": {
    "url": "http://localhost:3000/mcp/",
    "type": "http",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

Available Tools

Call tools/list for the live list. Highlights include:

Core Ethereum Tools

• eth_blockNumber (aliases: getBlockNumber, eth_getBlockNumber)
• eth_getBalance (alias: getBalance)
• eth_chainId (alias: getChainId)
• eth_gasPrice (alias: getGasPrice)
• eth_syncing (aliases: isSyncing, eth_isSyncing)
• eth_getBlockByNumber (alias: getBlock)
• eth_getTransactionByHash
• eth_call (alias: call)
• eth_estimateGas (alias: estimateGas)
• eth_getTransactionReceipt (alias: getTransactionReceipt)
• eth_getLogs (alias: getLogs)
• eth_getProof (alias: getProof)
• eth_sendRawTransaction (alias: sendRawTransaction, gated by ALLOW_SEND_RAW_TX)
• eth_callRaw (alias: ethCallRaw)

Block parameters accept tags like latest/pending or decimal/hex block numbers.

Admin Tools

• admin_peers (alias: getPeers)
• admin_nodeInfo

Debug Tools

• debug_metrics
• debug_traceTransaction (alias: traceTransaction)
• debug_blockProfile (alias: blockProfile)
• debug_getBlockRlp (alias: getBlockRlp)

Txpool Tools

• txpool_status

Contributing

Contributions are welcome! Please open an issue or submit a pull request for bug fixes, new tools, or improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.