Geth-mcp-proxy: Node.js Proxy Bridging Ethereum RPC to MCP for Secure Blockchain Data Access

Geth MCP Proxy

A Node.js-based proxy server that bridges Ethereum JSON-RPC queries from Geth nodes to the Model Context Protocol (MCP) ecosystem. It supports multiple Ethereum RPC methods as MCP-compatible tools, providing secure, rate-limited, and schema-validated blockchain data access.

Developer tools Finance #Ethereum Proxy #MCP Tools #Blockchain Bridging #Node Management .JavaScript

rating : 2 points

downloads : 5.4K

update time : 2025-08-19

Open Site

What is Geth MCP Proxy?

Geth MCP Proxy is a middleware service that transforms the complex technical interfaces of the Ethereum blockchain into a more user-friendly toolset. This enables non-technical users and AI systems to easily query blockchain data, send transactions, or perform debugging operations without directly interacting with the underlying Geth nodes.

How to use Geth MCP Proxy?

Simply call the predefined MCP tool names (such as getBalance for balance query) through simple HTTP requests. The proxy will automatically handle the complex communication with the Ethereum nodes and return formatted results. It supports both RESTful interfaces and the MCP protocol for invocation.

Applicable Scenarios

It is suitable for scenarios such as AI agents requiring blockchain data access, backend services of decentralized applications, and blockchain data analysis tools. It is particularly suitable for development teams that wish to avoid directly handling raw RPC calls.

Main Features

Ethereum RPC Bridging

Converts over 60 native Geth APIs into standardized tools, including account query, transaction sending, chain debugging and other functions.

Dual-Format Data

All numerical values are returned in both hexadecimal and decimal formats for easy use in different scenarios.

Safe Mode

The transaction sending function is disabled by default. You need to explicitly enable the ALLOW_SEND_RAW_TX environment variable.

Native MCP Support

Fully compatible with the Model Context Protocol specification, supporting standard endpoints such as tool discovery and health checks.

Advantages

Out-of-the-box full-featured Ethereum interface

Avoids the security risks of directly exposing Geth nodes

Automatically formats data, reducing the development burden

Modular design facilitates the expansion of new tools

Limitations

Performance is limited by Node.js's single-threaded model

Some advanced debugging functions require special startup parameters for Geth

The transaction function is disabled by default and requires additional configuration

How to Use

Environment Preparation

Ensure that Node.js v18+ is installed and a reachable Geth node is available.

Install the Service

Clone the repository and install dependencies.

Configure Parameters

Create a .env file to set the Geth node URL and port.

Start the Service

Run the main program to start the proxy server.

Usage Examples

Query Account Balance

An AI assistant needs to obtain the user's wallet balance to decide the transaction amount.

Transaction Simulation

The front - end of a DApp needs to estimate the gas consumption of a contract call.

Block Analysis

A data analysis tool needs to obtain the transaction list of a specific block.

Frequently Asked Questions

Why does the transaction sending fail?

How to add a new RPC method?

How to optimize performance bottlenecks?

Related Resources

GitHub Repository

Project source code and issue tracking

MCP Protocol Documentation

Official specification of the Model Context Protocol

Geth Management Guide

Configuration reference for Go Ethereum nodes

🚀 Geth MCP Proxy

This Node.js-based proxy server bridges Ethereum JSON-RPC queries from a Geth node to the Model Context Protocol (MCP) ecosystem, enabling seamless integration with MCP-enabled applications.

🚀 Quick Start

Clone the repository:

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

Install dependencies:
```
npm install
```
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)

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/
```

✨ 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

Clone the repository:

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

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.

💻 Usage Examples

Basic Usage

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.
Simple REST Endpoint:
- GET /blockNumber: Returns the current block number in hex and decimal.
Shutdown: Gracefully handles SIGINT/SIGTERM for clean shutdown.
Remember to add the mcp.json params to your .vscode/settings.json or mcp.json

Advanced Usage

If you want to use advanced features like enabling transaction broadcasting, set ALLOW_SEND_RAW_TX=1 in your .env file. Then you can use tools like eth_sendRawTransaction or sendRawTransaction to broadcast signed raw transactions.

📚 Documentation

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 Name	Description	Input Schema
`getBlockNumber` / `eth_getBlockNumber`	Retrieve the current block number (hex + decimal).	`{}`
`getBalance` / `eth_getBalance`	Get balance of an address (hex + decimal).	`{ address: string, block?: string }`
`eth_chainId` / `chainId`	Get current chain ID (hex + decimal).	`{}`
`eth_gasPrice` / `gasPrice`	Get current gas price (hex + wei decimal).	`{}`
`eth_isSyncing` / `isSyncing`	Check if the node is syncing.	`{}`
`eth_getBlockByNumber` / `getBlockByNumber`	Fetch block by number/tag.	`{ block: string, full?: boolean }`
`eth_getTransactionByHash` / `getTransactionByHash`	Fetch a transaction by hash.	`{ hash: string }`
`eth_call` / `call`	Execute a call without a transaction.	`{ to: string, data: string, block?: string }`
`eth_estimateGas` / `estimateGas`	Estimate gas for a transaction.	`{ to?: string, from?: string, data?: string, value?: string }`
`eth_sendRawTransaction` / `sendRawTransaction`	Broadcast a signed raw transaction (requires `ALLOW_SEND_RAW_TX=1`).	`{ rawTx: string }`
`ethCallRaw`	Call any Ethereum JSON - RPC method with params array.	`{ method: string, params?: any[] }`
`eth_simulateV1`	Simulate multiple blocks and transactions.	`{ payload: any, block: any }`
`eth_createAccessList`	Create an EIP2930 access list based on a transaction.	`{ transaction: any, blockNumberOrTag?: any }`
`eth_getHeaderByNumber`	Returns a block header by number.	`{ blockNumber: any }`
`eth_getHeaderByHash`	Returns a block header by hash.	`{ blockHash: string }`

Admin Tools

Tool Name	Description	Input Schema
`admin_exportChain`	Exports the blockchain to a file (optional range).	`{ file: string, first?: number, last?: number }`
`admin_importChain`	Imports blocks from a file.	`{ file: string }`
`admin_nodeInfo`	Retrieves node information.	`{}`
`admin_peers`	Retrieves connected peers information.	`{}`
`admin_removePeer`	Disconnects from a remote node.	`{ url: string }`
`admin_removeTrustedPeer`	Removes a remote node from trusted peers.	`{ url: string }`
`admin_startHTTP`	Starts an HTTP JSON - RPC server.	`{ host?: string, port?: number, cors?: string, apis?: string }`
`admin_startWS`	Starts a WebSocket JSON - RPC server.	`{ host?: string, port?: number, cors?: string, apis?: string }`
`admin_stopHTTP`	Stops the HTTP RPC endpoint.	`{}`
`admin_stopWS`	Stops the WebSocket RPC endpoint.	`{}`

Debug Tools

Tool Name	Description	Input Schema
`debug_accountRange`	Retrieves account range at a given block.	`{ blockNrOrHash: any, start: string, maxResults: number, nocode: boolean, nostorage: boolean, incompletes: boolean }`
`debug_backtraceAt`	Sets logging backtrace location.	`{ location: string }`
`debug_blockProfile`	Turns on block profiling.	`{ file: string, seconds: number }`
`debug_chaindbCompact`	Flattens the key - value database.	`{}`
`debug_chaindbProperty`	Returns leveldb properties.	`{ property: string }`
`debug_cpuProfile`	Turns on CPU profiling.	`{ file: string, seconds: number }`
`debug_dbAncient`	Retrieves ancient binary blob.	`{ kind: string, number: number }`
`debug_dbAncients`	Returns number of ancient items.	`{}`
`debug_dbGet`	Returns raw value of a key.	`{ key: string }`
`debug_dumpBlock`	Retrieves state for a block.	`{ number: number }`
`debug_freeOSMemory`	Forces garbage collection.	`{}`
`debug_freezeClient`	Forces a temporary client freeze.	`{ node: string }`
`debug_gcStats`	Returns GC statistics.	`{}`
`debug_getAccessibleState`	Returns first accessible state.	`{ from: any, to: any }`
`debug_getBadBlocks`	Returns last bad blocks.	`{}`
`debug_getRawBlock`	Retrieves RLP - encoded block.	`{ blockNrOrHash: any }`
`debug_getRawHeader`	Returns RLP - encoded header.	`{ blockNrOrHash: any }`
`debug_getRawTransaction`	Returns transaction bytes.	`{ hash: string }`
`debug_getModifiedAccountsByHash`	Returns modified accounts by hash.	`{ startHash: string, endHash?: string }`
`debug_getModifiedAccountsByNumber`	Returns modified accounts by number.	`{ startNum: number, endNum?: number }`
`debug_getRawReceipts`	Returns consensus - encoded receipts.	`{ blockNrOrHash: any }`
`debug_goTrace`	Turns on Go runtime tracing.	`{ file: string, seconds: number }`
`debug_intermediateRoots`	Executes block and returns intermediate roots.	`{ blockHash: string, options?: any }`
`debug_memStats`	Returns memory statistics.	`{}`
`debug_mutexProfile`	Turns on mutex profiling.	`{ file: string, nsec: number }`
`debug_preimage`	Returns preimage for sha3 hash.	`{ hash: string }`
`debug_printBlock`	Prints a block.	`{ number: number }`
`debug_setBlockProfileRate`	Sets block profile rate.	`{ rate: number }`
`debug_setGCPercent`	Sets GC target percentage.	`{ v: number }`
`debug_setHead`	Sets chain head by number.	`{ number: number }`
`debug_setMutexProfileFraction`	Sets mutex profile rate.	`{ rate: number }`
`debug_setTrieFlushInterval`	Sets trie flush interval.	`{ interval: string }`
`debug_stacks`	Returns goroutine stacks.	`{ filter?: string }`
`debug_standardTraceBlockToFile`	Traces block to file (standard JSON).	`{ blockHash: string, config?: any }`
`debug_standardTraceBadBlockToFile`	Traces bad block to file.	`{ blockHash: string, config?: any }`
`debug_startCPUProfile`	Starts CPU profiling.	`{ file: string }`
`debug_startGoTrace`	Starts Go trace.	`{ file: string }`
`debug_stopCPUProfile`	Stops CPU profiling.	`{}`
`debug_stopGoTrace`	Stops Go trace.	`{}`
`debug_storageRangeAt`	Returns storage at block height and tx index.	`{ blockHash: string, txIdx: number, contractAddress: string, keyStart: string, maxResult: number }`
`debug_traceBadBlock`	Traces bad block execution.	`{ blockHash: string, options?: any }`
`debug_traceBlock`	Traces block by RLP.	`{ blockRlp: string, options?: any }`
`debug_traceBlockByNumber`	Traces block by number.	`{ number: any, options?: any }`
`debug_traceBlockByHash`	Traces block by hash.	`{ hash: string, options?: any }`
`debug_traceBlockFromFile`	Traces block from file.	`{ fileName: string, options?: any }`
`debug_traceCall`	Traces an eth_call.	`{ args: any, blockNrOrHash: any, config?: any }`
`debug_traceTransaction`	Traces a transaction.	`{ txHash: string, options?: any }`
`debug_verbosity`	Sets logging verbosity.	`{ level: number }`
`debug_vmodule`	Sets logging verbosity pattern.	`{ pattern: string }`
`debug_writeBlockProfile`	Writes block profile.	`{ file: string }`
`debug_writeMemProfile`	Writes allocation profile.	`{ file: string }`
`debug_writeMutexProfile`	Writes mutex profile.	`{ file: string }`

Txpool Tools

Tool Name	Description	Input Schema
`txpool_content`	Retrieves all transactions in txpool.	`{}`
`txpool_contentFrom`	Retrieves transactions for an address.	`{ address: string }`
`txpool_inspect`	Lists textual summary of txpool.	`{}`
`txpool_status`	Returns txpool transaction counts.	`{}`