Web3 Docs

web3-docs

One MCP server, eleven protocol-spec repos. Ask your coding agent about EIPs, BIPs, ADRs, CIPs, RFCs and canonical contract addresses — without ever leaving your editor. Works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Cline, Zed, Continue, OpenCode, Codex, and more.

[](https://pypi.org/project/web3-docs-mcp/) [](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](https://github.com/dioptx/web3-docs/actions/workflows/ci.yml)

Or replay in your own terminal: asciinema play docs/assets/demo.cast

Why

Specs for blockchain protocols live across eleven different upstream repos on three different forges. Every time you need to look up EIP-4844, BIP-340, CIP-25, or which fork shipped PUSH0, you're tab-hunting through GitHub. This MCP indexes them all locally with FTS5 ranking — 1,767 proposals across 10 chains plus addresses for 19 protocols on Ethereum, Arbitrum, Base, Optimism, Polygon, and more — so your agent answers with the actual spec text, not a hallucinated paraphrase.

Install

> Requires: Python 3.11+ · uv (provides uvx) · ~500 MB free disk for the index · git on PATH (used by --sync).

Step 1 — build the index (one-time, ~2 min, ~500 MB in ~/.cache/web3-docs-mcp/)

uvx web3-docs-mcp --sync

Step 2 — register the server with your agent

The launch command is identical across clients:

uvx web3-docs-mcp

Claude Code

claude mcp add web3-docs -- uvx web3-docs-mcp

Cursor · Windsurf · Cline · Continue · Zed · generic stdio MCP client

Add to the client's MCP config (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, cline_mcp_settings.json, the mcpServers block in your Zed settings.json, etc.):

{
  "mcpServers": {
    "web3-docs": {
      "command": "uvx",
      "args": ["web3-docs-mcp"]
    }
  }
}

OpenAI Codex CLI

codex mcp add web3-docs -- uvx web3-docs-mcp

pip / pipx

pip install web3-docs-mcp
# or:
pipx install web3-docs-mcp

From source (development)

git clone https://github.com/dioptx/web3-docs.git && cd web3-docs
uv sync
uv run python server.py --sync   # build index
uv run python server.py          # run stdio server

Restart your agent, then try "Use web3-docs to look up EIP-1559."

What you can ask

| Ask your agent… | Tool chain | |---|---| | "What's the fee market in EIP-4844?" | resolve_proposal → query_protocol_docs(query="fee") | | "Show me Cosmos ADR-001." | resolve_proposal → query_protocol_docs | | "What's in Cancun?" | list_fork_proposals("Cancun") | | "Which BIPs activated with Taproot?" | list_fork_proposals("Taproot") | | "Uniswap router on Base?" | resolve_contract(protocol="uniswap", chain_id="8453") | | "Cardano CIP for native tokens?" | resolve_proposal("native tokens", chain="cardano") → cip-25 | | "ERC-4337 EntryPoint address on Arbitrum?" | resolve_contract("erc4337", "42161") | | "Staking on Cosmos vs Polkadot?" | resolve_proposal("staking", chain="cosmos") then chain="polkadot" |

Multi-chain canonical addresses, no etherscan tabs.

Tools

| Tool | What it does | |---|---| | resolve_proposal(query, chain?) | Fuzzy-find a proposal by keyword, fork name, opcode, or ID. Returns top-5 ranked hits with chain/status/fork. Pass chain= (ethereum, bitcoin, cosmos, …) to disambiguate when keywords match multiple chains. | | query_protocol_docs(proposal_id, query?) | Read the full spec body. With query, returns only the most relevant sections (token-budgeted). Includes metadata header (status, fork, activation date, authors). | | list_fork_proposals(fork_name) | List every proposal activated by a named fork. Answers "what's in Cancun?" / "BIPs activated with Taproot?". Handles aliases (Pectra → Prague, Dencun → Cancun, Shapella → Shanghai, The Merge → Paris). | | resolve_contract(protocol, chain_id?) | Look up canonical deployed addresses. 19 protocols × major EVM chains. Omit chain_id for all chains. |

Fork → all proposals it shipped, then drill into one. Two tool calls instead of an afternoon of tab-hunting.

Sources

11 upstream repos, all synced via --sync:

| Chain | Source | |---|---| | Ethereum (EIPs) | ethereum/EIPs | | Ethereum (ERCs) | ethereum/ERCs | | Bitcoin | bitcoin/bips | | Solana | solana-foundation/solana-improvement-documents | | Cosmos | cosmos/cosmos-sdk (docs/architecture) | | Polkadot | polkadot-fellows/RFCs | | Stacks | stacksgov/sips | | Avalanche | avalanche-foundation/ACPs | | Cardano | cardano-foundation/CIPs | | Tezos | tezos/tzip | | Sui | sui-foundation/sips |

Fork mappings come from ethereum/execution-specs plus canonical Bitcoin soft-fork activations (P2SH, SegWit, Taproot, …).

Contract registry covers: aave, across, chainlink, compound, create2_deployer, curve, ens, erc4337, gnosis_safe, lido, maker, multicall, oneinch, permit2, seaport, uniswap, usdc, usdt, weth.

Why not …

…just gh search or WebFetch each spec on demand? You'd burn tokens on HTML markup and pay a network round-trip per query. web3-docs indexes everything once into local SQLite + FTS5 — sub-millisecond ranked search, plain-text bodies, no rate limits, works offline.

…one MCP per chain? You'd manage eleven separate servers and your agent wouldn't know which to call. One unified tool with a single resolve_proposal entry point lets the model find the right doc by concept (e.g. "blob transactions" → eip-4844) rather than guessing the source.

…ask the model directly without an MCP? Models hallucinate spec details — wrong fork, wrong gas costs, wrong opcode numbers. This server returns the actual upstream text with metadata (status, fork, activation date) so the agent can quote it verbatim.

…use a vector DB? Spec corpora are small (≈ 1.7K docs), domain vocabulary is precise (PUSH0, BLOBHASH, taproot), and exact-term matching beats embeddings here. FTS5 gives BM25 ranking with zero infrastructure.

Configuration

| Env var | Default | Purpose | |---|---|---| | WEB3_DOCS_DATA_DIR | ~/.cache/web3-docs-mcp (macOS/Linux) | Where source repos and the SQLite index live |

Troubleshooting

"Index is empty" on any tool call. You haven't run --sync yet. Run:

uvx web3-docs-mcp --sync

uvx: command not found. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh.

Want to free disk space? Source repos (~/.cache/web3-docs-mcp/repos/) can be deleted after sync; only proposals.db is needed at runtime. Re-run --sync to update.

Stale data? Re-run --sync — it does a fast git pull and reindexes incrementally.

Development

git clone https://github.com/dioptx/web3-docs.git && cd web3-docs
uv sync --extra test
uv run pytest                  # 98 tests, BDD + unit
uv build                       # build wheel + sdist

Status

v0.2.0 — adds Cardano CIPs, Tezos TZIPs, Sui SIPs (10 chains, 1,767 proposals). SQLite + FTS5, FastMCP stdio transport. See [CHANGELOG.md](CHANGELOG.md) for release history.

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dioptx
• Source: dioptx/web3-docs
• License: MIT

Install and usage instructions live in the source repository linked above.