Give your LLM direct access to Ethereum specs, research, discussion, and history. All exposed as an MCP server.
- Sources
- Quickstart: local
- Quickstart: Use it in Claude or ChatGPT on the web
- Syncing the corpus locally
- Commands
- Better than grep
- Licensing
Everything in the corpus, as declared in sources.toml keep this list and the licensing table in sync when adding a source.
Suggest more sources!
| Source | What it is |
|---|---|
| ethresear.ch | Protocol R&D discussion, 2017–present |
| Ethereum Magicians | EIP process and hard-fork coordination |
| ethereum/EIPs | Core-protocol EIP specifications |
| ethereum/ERCs | Application-level ERC standards |
| consensus-specs | Consensus-layer specifications, per fork |
| execution-specs | EELS. The executable execution-layer spec, per fork |
| execution-apis | Engine API specifications, per fork |
| ethereum/pm | AllCoreDevs notes |
| vitalik.eth.limo | Vitalik's writing |
| EF blog | Ethereum Foundation announcements and research |
Skip the multi-hour source sync by downloading the latest corpus-* release.
Needs Rust (stable, 2024 edition) and ~1.5GB of disk.
git clone https://github.com/JossDuff/wikipethia && cd wikipethia
# Adds wikipethia to your PATH
cargo install --path wikipethia
# Download the latest released corpus
gh release download --pattern 'corpus-*' # or grab the assets from the Releases page
# verifies the downloaded corpus file wasn't corrupted or tampered with in transit
sha256sum -c corpus-*.sqlite.zst.sha256
# decompresses the downloaded corpus snapshot into a usable database file
zstd -d corpus-*.sqlite.zst -o corpus.sqlite
# Make sure wikipethia can access the corpus
wikipethia status
# connect the mcp server to to claude code
claude mcp add wikipethia -- wikipethia mcp --db $(pwd)/corpus.sqliteThen ask Ethereum protocol questions! The model cites forum posts, EIPs, and specs with URLs and dates.
Run wikipethia update at any time to update the corpus. It recrawls all the sources looking for new content. Takes ~10 minutes.
No CLI needed: a hosted, read-only wikipethia endpoint lives at
https://mcp.wikipethia.org/mcp
Claude (claude.ai):
On Team/Enterprise workspaces only an organization owner can add connectors; members then just click Connect.
- Settings → Connectors → Add custom connector
- Paste the URL above, no authentication needed
- Enable it from the chat's + menu and ask Ethereum questions
ChatGPT (chatgpt.com):
Needs Plus/Pro or above
- Settings → enable Developer mode (beta)
- Add an MCP server with the URL above, authentication: none
- Pick wikipethia from the + menu in a chat
The endpoint serves the same corpus the download gives you. It is run non-commercially: the two forums' content is CC BY-NC-SA 3.0, and every answer's citations carry the author, date, and source URL that attribution requires.
Expect several hours, most of it embedding (CPU) and a forum-friendly one-request-per-second crawl. Interrupting is safe: every stage is resumable and re-running picks up where it stopped. The first embed downloads a ~130MB model.
cd wikipethia
# Build the corpus. Runs three stages (fetch → index → embed):
wikipethia build
# Check what you have
wikipethia status
# connect the mcp server to to claude code
claude mcp add wikipethia -- wikipethia mcp --db $(pwd)/corpus.sqliteThen ask Ethereum protocol questions! The model cites forum posts, EIPs, and specs with URLs and dates.
Run wikipethia update at any time to update the corpus. It recrawls all the sources looking for new content. Takes ~10 minutes.
| Command | What it does |
|---|---|
build |
Fetch, index, and embed everything. The clone-day command. |
update |
Updates all sources, same three stages as build. Run periodically or cron job. |
status |
What the corpus holds, and whether it is ready to serve. |
search "<query>" |
Hybrid search from the terminal. |
sync / index / embed |
The three stages separately, for surgical use. |
dedup |
Report near-duplicate documents across sources. |
eval |
Retrieval eval: recall@10 over tests/eval/questions.toml. |
mcp |
Serve the corpus to LLM clients over MCP. stdio by default, streamable HTTP with --http; public hosting: see deploy/. |
agent-eval |
Whole-loop eval through a headless Claude Code session. Consumes real usage. |
publish |
Snapshot, compress, and release the corpus on GitHub. Maintainer command. |
--db <path> selects the corpus, --source <id> limits a command to one source, and refresh is a kept alias for update. --help on any command has the rest.
Search here is more than keyword matching, in three layers:
- Ranked lexical search (FTS5 + BM25). Keyword matches are scored: rare terms outweigh common ones, title/author hits outweigh body mentions, and stemming matches (ex: "exits" to "exit"). Exact tokens like
EIP-4844or an author name hit precisely. - Semantic search (embeddings). Every chunk of text is mapped by a small local model (BGE-small, via fastembed) to a point in vector space where meaning, not spelling, determines distance. A question about "PBS" finds proposer/builder-separation posts that never use the acronym.
- Hybrid fusion (RRF). Both rankings merge via reciprocal rank fusion: documents strong in either list surface, and exact-term hits are never diluted by the vector side.
Every result carries a stable doc id, author, published date, and URL.
Beyond ranked search, the MCP server answers exact spec identifiers directly: lookup_spec reads the indexed consensus-specs/EIP documents themselves and returns a constant's value or a spec function's Python body, per fork, with citations — no ranking involved, so a constant defined once in phase0 can't be drowned out by forum posts that mention it more often. Search can also be scoped to one source or fork (scope: "consensusspecs/specs/electra").
This repository's code is collectively licensed under the combined Source Seppuku License, Viral Public License, and GNU Affero General Public License v3.0.
The corpus itself contains material obtained from multiple sources under different licences. It is therefore not offered under a single licence. Each source remains subject to its original applicable licence. The source and applicable licence are identified in the corpus metadata and summarized below.
The compilation of material into this corpus does not relicense the underlying documents or expand the permissions granted by their original licences. Users must comply with the applicable licence for every document they download, reproduce, modify, distribute or use for model training or another purpose.
In particular, some sources are licensed only for non-commercial use, while others require attribution, preservation of licence notices or distribution of adaptations under the same licence. Users intending commercial use should exclude non-commercially licensed sources and independently verify that their proposed use satisfies all applicable conditions.
In short: for non-commercial use (research, learning, personal projects) the whole corpus is available, with credit. For commercial use, everything except the two forums (ethresear.ch and Ethereum Magicians) is available. Every document already carries its author, date, and URL, so attribution comes for free.
Every document, chunk, and search result also carries its source, so the corpus can be filtered down to whichever sources suit your licensing needs.