Exposes Ethereum RPC methods via MCP tools with validation, aliases, and passthrough support.
Configuration
View docs{
"mcpServers": {
"john0n1-geth-mcp": {
"url": "http://localhost:3000/mcp",
"headers": {
"PORT": "3000",
"GETH_URL": "http://localhost:8545",
"ALLOW_SEND_RAW_TX": "0"
}
}
}
}You run a lightweight Node.js proxy that exposes an Ethereum JSON-RPC endpoint as MCP tools, providing a beginner-friendly MCP surface with validation, readable responses, and a passthrough option for unregistered methods. This lets you query a local Geth node through a standardized MCP interface, discover available tools, and safely interact with the Ethereum RPC.
You can connect to the local MCP server from an MCP client to list available Ethereum-related tools, then call specific tools to interact with your Geth node. The setup focuses on convenient, validated tool exposure and includes a passthrough mechanism for methods that are not explicitly registered.
Key usage flows include discovering the tool catalog, initializing the MCP surface, listing core and admin tools, and performing calls such as querying balances, block numbers, and transaction information through a unified MCP interface. Administrative and debugging helpers are available, and a safe-by-default transaction broadcast mode can be enabled if needed.
Prerequisites: you need Node.js and npm installed on your system. You will run the MCP server from its project directory.
Step 1: Install dependencies for the MCP project.
Step 2: Create or edit your environment configuration to point to your Ethereum node.
Step 3: Start the MCP server and verify it is running.
The MCP server relies on environment variables to connect to your Ethereum node and to control behavior. The important variables shown are:
- GETH_URL: URL to your Geth node’s JSON-RPC endpoint (required). Example: http://localhost:8545
- PORT: Optional server port (default: 3000)
- ALLOW_SEND_RAW_TX: Optional flag to enable broadcasting raw transactions (default: 0) E.g., set to 1 to enable.
If your MCP client uses a local or remote configuration, point it to the MCP server endpoint that exposes the tools. The typical MCP path for this project is the server’s /mcp endpoint.
By default, raw transaction broadcasting is disabled for safety. Enable sending raw transactions only when you fully understand the implications and have appropriate controls in place.
If you encounter connectivity issues, verify that GETH_URL is correct and that your Geth node accepts HTTP RPC connections. Check that the MCP server’s port is not in use and that there are no firewall rules blocking the MCP URL.
Fetches the current block number on the connected Ethereum network. Aliases include getBlockNumber and eth_getBlockNumber.
Returns the balance of an account in wei. Alias: getBalance.
Retrieves the current chain ID. Alias: getChainId.
Obtains the current gas price in wei. Alias: getGasPrice.
Indicates whether the node is syncing. Aliases: isSyncing, eth_isSyncing.
Retrieves a block by its number or tag. Alias: getBlock.
Fetches a transaction by its hash.
Executes a message call locally without changing the blockchain. Alias: call.
Estimates gas for a given transaction. Alias: estimateGas.
Returns the receipt of a transaction by hash.
Retrieves logs that match given filter criteria. Alias: getLogs.
Retrieves account and storage proofs. Alias: getProof.
Broadcasts a signed raw transaction. Alias: sendRawTransaction. Requires ALLOW_SEND_RAW_TX to be enabled.
Passthrough for raw RPC calls via eth_callRaw. Alias: ethCallRaw.
Admin tool to list peers. Alias: getPeers.
Admin helper to fetch node information.
Debug endpoint for metrics.
Traces a transaction to provide execution details. Alias: traceTransaction.
Collects block profiling data. Alias: blockProfile.
Returns the RLP encoding of a block. Alias: getBlockRlp.
Shows the status of the TX pool.