eth-mcp 0.2.1

RAG-powered MCP server for Ethereum consensus specs and EIPs

ethereum-mcp

RAG-powered MCP server for Ethereum consensus specs, EIPs, and client source code.

What It Does

Indexes and searches across:

• Consensus Specs - Official beacon chain specifications
• EIPs - Ethereum Improvement Proposals
• Builder Specs - MEV-boost and PBS specifications
• Client Source Code - All major EL and CL implementations

Installation

# From PyPI
pip install ethereum-mcp

# From source
pip install -e .

# With client code parsing support
pip install -e ".[clients]"

# With Voyage API embeddings (best quality)
pip install -e ".[voyage]"

Quick Start

# Build the index (downloads specs + creates embeddings)
ethereum-mcp build

# Search the specs
ethereum-mcp search "slashing penalty"

# Check status
ethereum-mcp status

Features

Incremental Indexing

The v0.2.0 release introduces incremental indexing - only re-embeds changed files instead of rebuilding the entire index. This reduces update time from minutes to seconds.

# Update repos and incrementally re-index (fast!)
ethereum-mcp update

# Incremental index (default behavior)
ethereum-mcp index

# Preview what would change without indexing
ethereum-mcp index --dry-run

# Force full rebuild
ethereum-mcp index --full

How it works:

1. Tracks file hashes and modification times in a manifest
2. Detects which files changed since last index
3. Only re-embeds the changed content
4. Updates LanceDB incrementally (add/delete operations)

Configurable Embedding Models

Choose from multiple embedding models based on your quality/speed tradeoff:

# List available models
ethereum-mcp models

# Use a specific model
ethereum-mcp index --model codesage/codesage-large

Model	Dims	Quality	Speed	Notes
all-MiniLM-L6-v2	384	Fair	Fast	Default, good for quick searches
all-mpnet-base-v2	768	Good	Medium	Better quality
codesage/codesage-large	1024	Good	Medium	Code-specialized
voyage:voyage-code-3	1024	Excellent	API	Best quality, requires API key

Configure in ~/.ethereum-mcp/config.yaml:

embedding:
  model: "codesage/codesage-large"
  batch_size: 32

chunking:
  chunk_size: 1000
  chunk_overlap: 200

Expert Guidance

Curated knowledge beyond what's in the specs:

# Via CLI (when running as MCP server)
eth_expert_guidance("slashing")
eth_expert_guidance("mev")
eth_expert_guidance("maxeb")

Topics include: churn, slashing, maxeb, withdrawals, mev, pbs, epbs, mev_boost, flashbots

CLI Commands

# Full build pipeline
ethereum-mcp build                    # Specs + EIPs only
ethereum-mcp build --include-clients  # Include client source code
ethereum-mcp build --full             # Force full rebuild

# Individual steps
ethereum-mcp download                 # Clone consensus-specs, EIPs, builder-specs
ethereum-mcp download --include-clients
ethereum-mcp compile                  # Extract specs to JSON
ethereum-mcp index                    # Build vector embeddings
ethereum-mcp index --dry-run          # Preview changes
ethereum-mcp index --full             # Force full rebuild
ethereum-mcp index --model MODEL      # Use specific embedding model

# Update (git pull + incremental index)
ethereum-mcp update
ethereum-mcp update --full            # Update + force rebuild

# Search
ethereum-mcp search "slashing penalty"
ethereum-mcp search "attestation" --fork electra
ethereum-mcp search "EIP-4844" --limit 10

# Info
ethereum-mcp status                   # Index status, manifest info
ethereum-mcp models                   # List embedding models

MCP Tools

When running as an MCP server:

Tool	Purpose
eth_search	Unified search across specs + EIPs
eth_search_specs	Specs-only search (no EIPs)
eth_search_eip	EIP-specific search
eth_grep_constant	Fast constant lookup
eth_analyze_function	Get Python implementation from specs
eth_get_current_fork	Current fork (Electra/Pectra)
eth_list_forks	All upgrades with dates/epochs
eth_get_spec_version	Index metadata
eth_expert_guidance	Curated expert interpretations
eth_list_clients	List all EL/CL clients
eth_get_client	Details on specific client
eth_get_client_diversity	Diversity stats and health
eth_get_recommended_client_pairs	EL+CL pairing recommendations

Client Source Code

Execution Layer Clients

Client	Language	Organization
Geth	Go	Ethereum Foundation
Reth	Rust	Paradigm
Nethermind	C#	Nethermind
Erigon	Go	Erigon

Consensus Layer Clients

Client	Language	Organization
Prysm	Go	Offchain Labs
Lighthouse	Rust	Sigma Prime
Teku	Java	ConsenSys
Nimbus	Nim	Status

MEV Infrastructure

Project	Description
mev-boost	MEV-boost middleware
Flashbots Builder	Block builder reference
mev-boost-relay	Relay implementation
rbuilder	Rust block builder

# Download specific clients
ethereum-mcp download-clients --client reth --client lighthouse

# Download MEV infrastructure
ethereum-mcp download-clients --client mev-boost --client flashbots-builder

Project Structure

src/ethereum_mcp/
├── server.py               # MCP server (FastMCP)
├── cli.py                  # CLI commands
├── config.py               # Configuration management
├── clients.py              # Client tracking and diversity
├── indexer/
│   ├── downloader.py       # Git clone specs + clients
│   ├── compiler.py         # Spec extraction
│   ├── client_compiler.py  # Multi-language client parsing
│   ├── chunker.py          # Document chunking + chunk IDs
│   ├── embedder.py         # Embeddings + LanceDB + incremental
│   └── manifest.py         # File tracking for incremental updates
└── expert/
    └── guidance.py         # Curated interpretations

Data Location

~/.ethereum-mcp/
├── config.yaml             # Configuration (optional)
├── manifest.json           # Index state tracking
├── consensus-specs/        # Cloned specs repo
├── EIPs/                   # Cloned EIPs repo
├── builder-specs/          # Cloned builder-specs repo
├── clients/                # Client source code (optional)
├── compiled/               # Extracted JSON
└── lancedb/                # Vector index

Fork History

Fork	Epoch	Date	Description
Phase0	0	2020-12-01	Beacon chain genesis
Altair	74240	2021-10-27	Light clients, sync committees
Bellatrix	144896	2022-09-06	Merge preparation
Capella	194048	2023-04-12	Withdrawals enabled
Deneb	269568	2024-03-13	Proto-danksharding (EIP-4844)
Electra	364032	2025-05-07	MaxEB, consolidations
Fulu	411392	2025-11-15	PeerDAS, verkle prep

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=ethereum_mcp

# Lint
ruff check src/

Running as MCP Server

# Start the server
eth-mcp

# Or with uvicorn for development
uvicorn ethereum_mcp.server:mcp --reload

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "ethereum": {
      "command": "eth-mcp"
    }
  }
}

Documentation

• Incremental Indexing - How the incremental update system works
• CLAUDE.md - Quick reference for Claude Code

License

MIT