MCP Server

The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants (such as Claude Desktop) to securely connect to external data sources and tools. MCP defines a uniform interface through which an AI model can discover, read, and invoke capabilities provided by a server — without needing any custom integration code.

Erigon ships a full MCP server implementation. Once connected, an AI assistant gains structured, read-only access to Ethereum blockchain data, Erigon logs, and internal metrics — turning natural-language questions into precise on-chain lookups.

tip

MCP is a read-only interface: the server exposes query tools only. No write operations (sending transactions, changing state) are available.

Two Server Variants

Erigon provides two ways to run the MCP server:

Embedded (inside Erigon)

The MCP server runs inside the main erigon process, with direct access to internal APIs and Prometheus metrics. It is enabled by default on 127.0.0.1:8553:

# MCP server starts automatically on 127.0.0.1:8553
./build/bin/erigon --datadir=./data

To disable the embedded MCP server entirely, pass --mcp.disable:

./build/bin/erigon --datadir=./data --mcp.disable

This mode uses SSE (Server-Sent Events) transport over HTTP and is the simplest option when you are already running a full Erigon node.

Standalone (`mcp` binary)

A separate mcp binary that connects to an existing Erigon node either via its JSON-RPC endpoint or directly via the MDBX database. Supports both stdio (for Claude Desktop) and SSE transports.

make mcp
./build/bin/mcp --help

Configuration

Flags (embedded mode)

Flag	Default	Description
`--mcp.disable`	`false`	Disable the embedded MCP server entirely
`--mcp.addr`	`127.0.0.1`	Listening address for the embedded MCP server
`--mcp.port`	`8553`	Listening port for the embedded MCP server

info

The embedded MCP server is enabled by default and listens on 127.0.0.1:8553. Because it binds to localhost only, it is not reachable from external networks. If you do not need AI-assistant integration, pass --mcp.disable to avoid opening the port. If you are running multiple Erigon instances on the same machine, assign distinct ports with --mcp.port to avoid conflicts.

Flags (standalone `mcp` binary)

Flag	Default	Description
`--rpc.url`	`http://127.0.0.1:8545`	Erigon JSON-RPC endpoint to proxy
`--port`	—	Shorthand for `--rpc.url http://127.0.0.1:<port>`
`--datadir`	—	Erigon data directory (enables direct DB access mode)
`--private.api.addr`	`127.0.0.1:9090`	gRPC private API address (used with `--datadir`)
`--transport`	`stdio`	Transport type: `stdio` or `sse`
`--sse.addr`	`127.0.0.1:8553`	SSE listen address (when `--transport sse`)
`--log.dir`	—	Path to Erigon log directory (enables log analysis tools)

Connection Modes (standalone)

The standalone mcp binary supports three connection modes, tried in priority order:

1. JSON-RPC Proxy (recommended)

Forwards tool calls to a running Erigon node's HTTP JSON-RPC endpoint. Works with any Erigon instance that has the RPC server enabled.

# Explicit URL
./build/bin/mcp --rpc.url http://127.0.0.1:8545

# Port shorthand
./build/bin/mcp --port 8545

# With log analysis enabled
./build/bin/mcp --port 8545 --log.dir /data/erigon/logs

2. Direct Datadir Access

Opens Erigon's MDBX database directly — similar to an external rpcdaemon. Requires either a running Erigon instance with the gRPC private API, or read-only local disk access.

# gRPC + direct DB
./build/bin/mcp --datadir /data/erigon --private.api.addr 127.0.0.1:9090

# Default private.api.addr (127.0.0.1:9090)
./build/bin/mcp --datadir /data/erigon

3. Auto-Discovery

When started without flags, the binary probes localhost:8545, 8546, and 8547 for a running JSON-RPC endpoint:

./build/bin/mcp

Use Cases

Interactive Blockchain Analysis

Connect your AI assistant to a running Erigon node and ask natural-language questions about on-chain data without writing a single line of code.

"What is the ETH balance of vitalik.eth right now, and how many transactions has it sent?"

The assistant calls eth_getBalance and eth_getTransactionCount on the address, formats the results in human-readable form, and summarises the answer.

"Show me all ERC-20 Transfer events emitted in the last 100 blocks from contract 0xA0b…"

The assistant calls eth_getLogs with the appropriate filter, decodes the ABI-encoded topics, and presents a table of transfers with amounts and counterparties.

"Which transactions in block 21,000,000 consumed the most gas?"

The assistant calls eth_getBlockByNumber and eth_getBlockReceipts, sorts by gas used, and returns the top offenders with links to the relevant hashes.

Node Debugging and Monitoring

When something looks wrong with your node, ask the assistant to sift through logs and metrics for you.

"My node seems stuck. Check the sync status and the last 50 log lines for any errors."

The assistant calls eth_syncing to get the current sync progress, then uses logs_tail and logs_grep to search for ERROR or WARN entries — surfacing actionable information without requiring you to SSH into the server.

"Are there any unusual patterns in the torrent download stats over the last hour?"

Using the torrent_status prompt and logs_stats, the assistant analyses download throughput, stall events, and peer connectivity in a single conversational turn.

Setting Up with Claude Desktop

Add the following to your Claude Desktop configuration file (~/.config/claude-desktop/config.json on Linux/macOS, %APPDATA%\claude-desktop\config.json on Windows):

JSON-RPC mode
Datadir mode
Embedded (SSE)

{
  "mcpServers": {
    "erigon": {
      "command": "/path/to/build/bin/mcp",
      "args": ["--port", "8545", "--log.dir", "/data/erigon/logs"]
    }
  }
}

{
  "mcpServers": {
    "erigon": {
      "command": "/path/to/build/bin/mcp",
      "args": ["--datadir", "/data/erigon"]
    }
  }
}

{
  "mcpServers": {
    "erigon": {
      "type": "sse",
      "url": "http://127.0.0.1:8553/sse"
    }
  }
}

The embedded MCP server starts by default on 127.0.0.1:8553. To use a different address or port, pass --mcp.addr and --mcp.port. To disable it, pass --mcp.disable.

After saving, restart Claude Desktop. The Erigon tools will appear in the tool panel under erigon.

Setting Up with Claude Code

Claude Code is Anthropic's CLI coding agent. Register the Erigon MCP server with a single command — no config file editing required.

Embedded SSE mode (recommended — zero extra binaries):

claude mcp add --transport sse erigon http://127.0.0.1:8553/sse

Standalone stdio mode:

claude mcp add erigon /path/to/build/bin/mcp -- --port 8545

Verify the server is registered:

claude mcp list

Once added, Claude Code discovers the Erigon tools automatically at the start of every session. You can then ask natural-language questions about your node inline while coding — for example: "What is the current block number?" or "Show sync status" — and Claude will call the appropriate tool against your local node.

To remove the server:

claude mcp remove erigon

Setting Up with OpenAI Codex

OpenAI Codex CLI supports MCP servers via ~/.codex/config.yaml. Add the mcp_servers key to your existing config file:

Embedded SSE
Standalone stdio

mcp_servers:
  erigon:
    type: sse
    url: http://127.0.0.1:8553/sse

mcp_servers:
  erigon:
    command: /path/to/build/bin/mcp
    args:
      - --port
      - "8545"

Save the file and start a new Codex session. The Erigon tools are loaded automatically — you can query your node in natural language alongside any coding task.

tip

The embedded SSE mode (http://127.0.0.1:8553/sse) works out of the box as long as Erigon is running. No separate binary is needed.

Available Tools

The MCP server exposes over 40 tools grouped by namespace:

Ethereum Standard (`eth_*`)

Standard JSON-RPC methods exposed as MCP tools: eth_blockNumber, eth_getBlockByNumber, eth_getBlockByHash, eth_getBalance, eth_getTransactionByHash, eth_getTransactionReceipt, eth_getBlockReceipts, eth_getLogs, eth_getCode, eth_getStorageAt, eth_getTransactionCount, eth_call, eth_estimateGas, eth_gasPrice, eth_chainId, eth_syncing, eth_getProof, and more.

Erigon-Specific (`erigon_*`)

erigon_nodeInfo, erigon_forks, erigon_getBlockByTimestamp, erigon_getBalanceChangesInBlock, erigon_getLogsByHash, erigon_getBlockReceiptsByBlockHash, and more.

Otterscan (`ots_*`)

ots_getInternalOperations, ots_searchTransactionsBefore, ots_searchTransactionsAfter, ots_getBlockDetails, ots_traceTransaction, ots_getTransactionError, ots_getContractCreator, and more.

Log Analysis (`logs_*`)

logs_tail, logs_head, logs_grep, logs_stats — require --log.dir or --datadir to locate Erigon log files.

Metrics (`metrics_*`)

metrics_list, metrics_get — available in embedded mode only. In standalone mode these return a descriptive message.

Resources and Prompts

In addition to tools, the MCP server exposes structured resources and prompts:

Resources (addressable by URI):

Resource	Description
`erigon://node/info`	Node version, chain, capabilities
`erigon://chain/config`	Full chain configuration
`erigon://blocks/recent`	Last 10 blocks summary
`erigon://network/status`	Sync state and peer count
`erigon://gas/current`	Current gas price
`erigon://address/{address}/summary`	Balance, nonce, contract status
`erigon://block/{number}/summary`	Block summary
`erigon://transaction/{hash}/analysis`	Transaction analysis

Prompts (pre-built analysis templates):

Prompt	Description
`analyze_transaction`	Deep-dive into a transaction
`investigate_address`	Profile an address (balance, history, code)
`analyze_block`	Summarise a block and its transactions
`gas_analysis`	Current and historical gas price analysis
`debug_logs`	Triage node issues from recent log output
`torrent_status`	Snapshot download health check
`sync_analysis`	Node sync progress and performance

Two Server Variants​

Embedded (inside Erigon)​

Standalone (mcp binary)​

Configuration​

Flags (embedded mode)​

Flags (standalone mcp binary)​

Connection Modes (standalone)​

1. JSON-RPC Proxy (recommended)​

2. Direct Datadir Access​

3. Auto-Discovery​

Use Cases​

Interactive Blockchain Analysis​

Node Debugging and Monitoring​

Setting Up with Claude Desktop​

Setting Up with Claude Code​

Setting Up with OpenAI Codex​

Available Tools​

Ethereum Standard (eth_*)​

Erigon-Specific (erigon_*)​

Otterscan (ots_*)​

Log Analysis (logs_*)​

Metrics (metrics_*)​

Resources and Prompts​