This MCP server exposes an Ethereum JSON-RPC endpoint via an Express-based Node.js proxy. It registers a suite of MCP tools that map common Ethereum RPC methods (such as eth_blockNumber, eth_getBalance, eth_sendRawTransaction, and eth_call) into MCP-accessible tools, with validation and aliases to simplify usage. The server also provides passthrough support (eth_callRaw) for methods not explicitly defined and includes health and discovery endpoints at /, /health, and /mcp. To use it, configure a GETH_URL to point to your Ethereum node and start the server. You can then query the MCP interface to list available tools and call specific tools by name, or interact with the underlying JSON-RPC API through the provided endpoints. Block numbers, balances, and gas prices are normalized to decimal where applicable, and you can enable raw transaction submissions by setting ALLOW_SEND_RAW_TX=1.

Prerequisites:

• Node.js v18+ installed
• npm or pnpm installed

Step-by-step:

1. Clone the repository git clone https://github.com/John0n1/ethereum-mcp.git cd ethereum-mcp

2. Install dependencies npm install

3. Create and configure environment

   • Copy the example env file and edit GETH_URL

     PowerShell

     Copy-Item example.env .env

     macOS/Linux

     cp example.env .env

   • Edit .env to set GETH_URL (and optional PORT and ALLOW_SEND_RAW_TX)

4. Start the server npm start

5. Verify the server is running curl http://localhost:3000/health?upstream=1

6. Interact with MCP tools List tools: curl -s http://localhost:3000/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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

Tips and common considerations:

• Ensure GETH_URL points to a reachable Ethereum node with JSON-RPC enabled (and appropriate http/ws flags if needed).
• If you need to broadcast transactions, set ALLOW_SEND_RAW_TX=1; otherwise, eth_sendRawTransaction calls may be rejected.
• The MCP tools offer aliases for convenience (e.g., eth_blockNumber as getBlockNumber).
• The /health endpoint can optionally verify upstream connectivity with ?upstream=1; use this to monitor upstream availability.
• If you run behind a reverse proxy, remember to configure CORS and any required headers for your environment.