Geth-MCP-Proxy

John0n1/Geth-MCP-Proxy

3.2

If you are the rightful owner of Geth-MCP-Proxy and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Geth MCP Proxy is a Node.js-based server that bridges Ethereum JSON-RPC queries to the Model Context Protocol (MCP) ecosystem.

Tools
5
Resources
0
Prompts
0

Geth MCP Proxy

Node.js Express.js License: MIT

Introduction

This project is a Node.js-based proxy server that bridges Ethereum JSON-RPC queries from a Geth (Go Ethereum) node to the Model Context Protocol (MCP) ecosystem. It exposes a wide range of Ethereum RPC methods as MCP-compatible "tools," allowing seamless integration with MCP-enabled applications, such as AI models or decentralized systems that require controlled access to blockchain data.

The proxy acts as an intermediary, handling requests to a Geth endpoint specified via environment variables. It registers tools for common Ethereum operations (e.g., querying block numbers, balances, transactions) as well as advanced admin and debug functions. Responses are formatted with both hexadecimal and decimal values where applicable for easier consumption. A generic passthrough tool (ethCallRaw) allows calling any unsupported RPC method.

screenshot_vscode_3

Key features include:

  • Zod schema validation for tool inputs.
  • Optional enabling of transaction broadcasting.
  • Support for MCP streaming and direct tool calls via HTTP.
  • A simple REST endpoint for quick block number queries.

This setup ensures secure, rate-limited, and schema-validated access to Ethereum data, making it ideal for applications that need to interact with the blockchain without direct exposure to the Geth RPC.

Features

  • MCP Integration: Registers Ethereum RPC methods as MCP tools with defined schemas and handlers.
  • Ethereum RPC Coverage: Supports core methods (e.g., eth_blockNumber, eth_getBalance), aliases, admin tools (e.g., chain export/import, peer management), and debug tools (e.g., tracing, profiling).
  • Data Formatting: Automatically converts hex values to decimal for readability (e.g., block numbers, balances, gas prices).
  • Security Controls: Transaction sending is disabled by default; enable via ALLOW_SEND_RAW_TX=1.
  • Health and Discovery Endpoints: MCP-compatible /mcp routes for initialization, tool listing, and health checks.
  • Fallback Passthrough: Use ethCallRaw for any JSON-RPC method not explicitly registered.
  • Environment-Driven: Configured via .env file for Geth URL and port.

Installation

  1. Clone the repository:

    git clone https://github.com/John0n1/Geth-MCP-Proxy.git
cd Geth-MCP-Proxy

  2. Install dependencies:

    npm install

    Required packages:

    • dotenv: For environment variable management.
    • express: Web server framework.
    • @modelcontextprotocol/sdk: MCP SDK for tool registration and transport.
    • zod: Input validation schemas.
    • fs: Built-in file system utilities.

Configuration

Create a .env file in the root directory with the following variables:

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 to enable transaction broadcasting (disabled by default for security)
  • GETH_URL: Mandatory. Points to your Ethereum node's RPC (e.g., local Geth or Infura).
  • Ensure your Geth node is running and accessible. For admin/debug methods, Geth must be started with --rpc.allow-unprotected-txs or equivalent flags if needed.

Usage

  1. Start the server:

    node mcpServer.js

    The server will listen on http://localhost:3000 (or your specified port) and log:

    🚀 MCP server listening at http://localhost:3000/mcp/

  2. MCP Endpoints:

    • Health Check: GET /mcp or GET /mcp/ – Returns server status and registered tools.
    • Initialize: POST /mcp with JSON-RPC payload { "method": "initialize" }.
    • List Tools: POST /mcp with { "method": "tools/list" } – Returns a list of available tools with descriptions and schemas.
    • Call Tool: POST /mcp with { "method": "tools/call", "params": { "name": "toolName", "arguments": {} } }.
    • Supports streaming for multi-message sessions via MCP transport.
screenshot_vscode_4

  1. Simple REST Endpoint:

    • GET /blockNumber: Returns the current block number in hex and decimal.

  2. Shutdown: Gracefully handles SIGINT/SIGTERM for clean shutdown.

  3. Remember to add the mcp.json params to your .vscode/ settings.json or mcp.json

Available Tools

The proxy registers the following MCP tools, grouped by category. Each tool includes a description, input schema (Zod-based), and handler that queries Geth.

Core Ethereum Tools

Tool NameDescriptionInput Schema
getBlockNumber / eth_getBlockNumberRetrieve the current block number (hex + decimal).{}
getBalance / eth_getBalanceGet balance of an address (hex + decimal).{ address: string, block?: string }
eth_chainId / chainIdGet current chain ID (hex + decimal).{}
eth_gasPrice / gasPriceGet current gas price (hex + wei decimal).{}
eth_isSyncing / isSyncingCheck if the node is syncing.{}
eth_getBlockByNumber / getBlockByNumberFetch block by number/tag.{ block: string, full?: boolean }
eth_getTransactionByHash / getTransactionByHashFetch a transaction by hash.{ hash: string }
eth_call / callExecute a call without a transaction.{ to: string, data: string, block?: string }
eth_estimateGas / estimateGasEstimate gas for a transaction.{ to?: string, from?: string, data?: string, value?: string }
eth_sendRawTransaction / sendRawTransactionBroadcast a signed raw transaction (requires ALLOW_SEND_RAW_TX=1).{ rawTx: string }
ethCallRawCall any Ethereum JSON-RPC method with params array.{ method: string, params?: any[] }
eth_simulateV1Simulate multiple blocks and transactions.{ payload: any, block: any }
eth_createAccessListCreate an EIP2930 access list based on a transaction.{ transaction: any, blockNumberOrTag?: any }
eth_getHeaderByNumberReturns a block header by number.{ blockNumber: any }
eth_getHeaderByHashReturns a block header by hash.{ blockHash: string }

Admin Tools

Tool NameDescriptionInput Schema
admin_exportChainExports the blockchain to a file (optional range).{ file: string, first?: number, last?: number }
admin_importChainImports blocks from a file.{ file: string }
admin_nodeInfoRetrieves node information.{}
admin_peersRetrieves connected peers information.{}
admin_removePeerDisconnects from a remote node.{ url: string }
admin_removeTrustedPeerRemoves a remote node from trusted peers.{ url: string }
admin_startHTTPStarts an HTTP JSON-RPC server.{ host?: string, port?: number, cors?: string, apis?: string }
admin_startWSStarts a WebSocket JSON-RPC server.{ host?: string, port?: number, cors?: string, apis?: string }
admin_stopHTTPStops the HTTP RPC endpoint.{}
admin_stopWSStops the WebSocket RPC endpoint.{}

Debug Tools

Tool NameDescriptionInput Schema
debug_accountRangeRetrieves account range at a given block.{ blockNrOrHash: any, start: string, maxResults: number, nocode: boolean, nostorage: boolean, incompletes: boolean }
debug_backtraceAtSets logging backtrace location.{ location: string }
debug_blockProfileTurns on block profiling.{ file: string, seconds: number }
debug_chaindbCompactFlattens the key-value database.{}
debug_chaindbPropertyReturns leveldb properties.{ property: string }
debug_cpuProfileTurns on CPU profiling.{ file: string, seconds: number }
debug_dbAncientRetrieves ancient binary blob.{ kind: string, number: number }
debug_dbAncientsReturns number of ancient items.{}
debug_dbGetReturns raw value of a key.{ key: string }
debug_dumpBlockRetrieves state for a block.{ number: number }
debug_freeOSMemoryForces garbage collection.{}
debug_freezeClientForces a temporary client freeze.{ node: string }
debug_gcStatsReturns GC statistics.{}
debug_getAccessibleStateReturns first accessible state.{ from: any, to: any }
debug_getBadBlocksReturns last bad blocks.{}
debug_getRawBlockRetrieves RLP-encoded block.{ blockNrOrHash: any }
debug_getRawHeaderReturns RLP-encoded header.{ blockNrOrHash: any }
debug_getRawTransactionReturns transaction bytes.{ hash: string }
debug_getModifiedAccountsByHashReturns modified accounts by hash.{ startHash: string, endHash?: string }
debug_getModifiedAccountsByNumberReturns modified accounts by number.{ startNum: number, endNum?: number }
debug_getRawReceiptsReturns consensus-encoded receipts.{ blockNrOrHash: any }
debug_goTraceTurns on Go runtime tracing.{ file: string, seconds: number }
debug_intermediateRootsExecutes block and returns intermediate roots.{ blockHash: string, options?: any }
debug_memStatsReturns memory statistics.{}
debug_mutexProfileTurns on mutex profiling.{ file: string, nsec: number }
debug_preimageReturns preimage for sha3 hash.{ hash: string }
debug_printBlockPrints a block.{ number: number }
debug_setBlockProfileRateSets block profile rate.{ rate: number }
debug_setGCPercentSets GC target percentage.{ v: number }
debug_setHeadSets chain head by number.{ number: number }
debug_setMutexProfileFractionSets mutex profile rate.{ rate: number }
debug_setTrieFlushIntervalSets trie flush interval.{ interval: string }
debug_stacksReturns goroutine stacks.{ filter?: string }
debug_standardTraceBlockToFileTraces block to file (standard JSON).{ blockHash: string, config?: any }
debug_standardTraceBadBlockToFileTraces bad block to file.{ blockHash: string, config?: any }
debug_startCPUProfileStarts CPU profiling.{ file: string }
debug_startGoTraceStarts Go trace.{ file: string }
debug_stopCPUProfileStops CPU profiling.{}
debug_stopGoTraceStops Go trace.{}
debug_storageRangeAtReturns storage at block height and tx index.{ blockHash: string, txIdx: number, contractAddress: string, keyStart: string, maxResult: number }
debug_traceBadBlockTraces bad block execution.{ blockHash: string, options?: any }
debug_traceBlockTraces block by RLP.{ blockRlp: string, options?: any }
debug_traceBlockByNumberTraces block by number.{ number: any, options?: any }
debug_traceBlockByHashTraces block by hash.{ hash: string, options?: any }
debug_traceBlockFromFileTraces block from file.{ fileName: string, options?: any }
debug_traceCallTraces an eth_call.{ args: any, blockNrOrHash: any, config?: any }
debug_traceTransactionTraces a transaction.{ txHash: string, options?: any }
debug_verbositySets logging verbosity.{ level: number }
debug_vmoduleSets logging verbosity pattern.{ pattern: string }
debug_writeBlockProfileWrites block profile.{ file: string }
debug_writeMemProfileWrites allocation profile.{ file: string }
debug_writeMutexProfileWrites mutex profile.{ file: string }

Txpool Tools

Tool NameDescriptionInput Schema
txpool_contentRetrieves all transactions in txpool.{}
txpool_contentFromRetrieves transactions for an address.{ address: string }
txpool_inspectLists textual summary of txpool.{}
txpool_statusReturns txpool transaction counts.{}

Contributing

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

License

MIT

License

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