Geth MCP Server

A Model Context Protocol (MCP) server for interacting with Geth blockchain nodes. This is a pure MCP server that communicates via stdio transport without requiring any port listeners.

Features

• 10 MCP Tools: Comprehensive blockchain interaction tools
• Pure MCP Server: Runs via stdio transport (no HTTP server or ports)
• Web3 Integration: Direct connection to your local Geth node at http://localhost:8545
• BigInt Support: Proper handling of blockchain data with BigInt values
• Comprehensive Error Handling: Robust error handling for all blockchain operations

Available MCP Tools

1. get_block_info: Get detailed information about a specific block by number or hash
2. get_account_balance: Check the balance of an Ethereum account
3. get_transaction_info: Get comprehensive transaction details
4. get_latest_block: Fetch information about the latest block
5. get_network_info: Get network status and node information
6. get_gas_price: Check current gas prices
7. get_storage_at: Get storage values from specific positions in smart contracts
8. get_logs: Fetch event logs based on filter criteria
9. get_code: Get the bytecode of contracts at specific addresses
10. estimate_gas: Estimate gas required for transactions with cost calculations

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g geth-mcp-server

# Or install locally in your project
npm install geth-mcp-server

Option 2: Build from Source

git clone https://github.com/your-username/geth-mcp-server.git
cd geth-mcp-server
npm install
npm run build

Usage

Using the npm Package

After installing via npm, you can use the server directly:

# If installed globally
geth-mcp-server

# If installed locally
npx geth-mcp-server

Using from Source

# Development mode
npm run dev

# Production mode
npm run build
npm start

MCP Configuration

For npm Installation

Use this configuration in your MCP client (like Claude Desktop):

{
  "mcpServers": {
    "geth-mcp-server": {
      "command": "npx",
      "args": ["geth-mcp-server"],
      "env": {
        "GETH_URL": "http://localhost:8545"
      }
    }
  }
}

For Global npm Installation

{
  "mcpServers": {
    "geth-mcp-server": {
      "command": "geth-mcp-server",
      "args": [],
      "env": {
        "GETH_URL": "http://localhost:8545"
      }
    }
  }
}

For Source Installation

{
  "mcpServers": {
    "geth-mcp-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/geth-mcp-server",
      "env": {
        "GETH_URL": "http://localhost:8545"
      }
    }
  }
}

Configuration

• Geth URL: http://localhost:8545 (configured via GETH_URL environment variable)
• Transport: stdio only (no HTTP server or ports)

MCP Tool Examples

Get Latest Block

{
  "tool": "get_latest_block",
  "arguments": {}
}

Check Account Balance

{
  "tool": "get_account_balance",
  "arguments": {
    "address": "0x742d35cc6Cc6ab4b3569bB50915BF3a3bF6dEc76"
  }
}

Get Block Info

{
  "tool": "get_block_info",
  "arguments": {
    "blockIdentifier": "latest"
  }
}

Get Contract Storage

{
  "tool": "get_storage_at",
  "arguments": {
    "address": "0x742d35cc6Cc6ab4b3569bB50915BF3a3bF6dEc76",
    "position": "0x0"
  }
}

Get Event Logs

{
  "tool": "get_logs",
  "arguments": {
    "fromBlock": "latest",
    "toBlock": "latest",
    "address": "0x742d35cc6Cc6ab4b3569bB50915BF3a3bF6dEc76"
  }
}

Estimate Gas

{
  "tool": "estimate_gas",
  "arguments": {
    "from": "0x742d35cc6Cc6ab4b3569bB50915BF3a3bF6dEc76",
    "to": "0x742d35cc6Cc6ab4b3569bB50915BF3a3bF6dEc76",
    "value": "1000000000000000000"
  }
}

Tool Details

Contract Inspection Tools

• get_code: Returns contract bytecode and indicates if address is a contract
• get_storage_at: Reads specific storage slots in smart contracts
• get_logs: Filters and retrieves event logs with flexible criteria

Transaction Analysis Tools

• estimate_gas: Provides gas estimates with cost calculations in Wei, Gwei, and ETH
• get_transaction_info: Comprehensive transaction data including receipt information

Blockchain Data Tools

• get_latest_block: Current block information
• get_block_info: Historical block data by number or hash
• get_account_balance: Account balances in multiple units
• get_network_info: Network status and node information
• get_gas_price: Current gas pricing data

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues
• Invalid blockchain data requests
• Malformed tool parameters
• Web3 provider errors
• BigInt serialization issues

Quick Start Guide

1. Install the package:

   npm install -g geth-mcp-server

2. Ensure Geth is running:

   # Start your local Geth node
   geth --http --http.addr localhost --http.port 8545 --http.corsdomain "*" --http.api eth,net,web3

3. Configure your MCP client with the configuration shown above

4. Start using the tools through your MCP client

NPM Package

• Package Name: geth-mcp-server
• Version: 1.0.0
• Registry: https://www.npmjs.com/package/geth-mcp-server
• Size: 7.7 kB compressed, 40.2 kB unpacked

Requirements

• Node.js 18+
• Access to a running Geth node (default: http://localhost:8545)
• MCP-compatible client for interaction

License

MIT