Geth MCP Proxy

Introduction

This project is a Node.js proxy that exposes an Ethereum JSON-RPC endpoint (Geth) as MCP tools. It focuses on a beginner-friendly MCP surface with schema validation, readable responses, and a passthrough tool (eth_callRaw) for any method that is not explicitly registered.

Features

• MCP tool registration with Zod validation and friendly aliases.
• Common Ethereum RPC methods plus a small set of admin/debug/txpool helpers.
• Hex to decimal formatting for block numbers, balances, and gas prices.
• Safe-by-default transaction broadcasting (ALLOW_SEND_RAW_TX=1 to enable).
• Health and discovery endpoints (/, /health, /mcp).
• Passthrough JSON-RPC via eth_callRaw (respects send-raw-tx safety).

Quickstart

1. Clone and install:

   git clone https://github.com/John0n1/Geth-MCP-Proxy.git
   cd Geth-MCP-Proxy
   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 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:

{
  "geth-mcp-proxy": {
    "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.