Skip to main content
Glama

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.

PyPI version License: MIT Python 3.11+ MCP CI

web3-docs MCP demo

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.

Related MCP server: yksanjo/gmem

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 mcp add web3-docs -- uvx web3-docs-mcp

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"]
    }
  }
}
codex mcp add web3-docs -- uvx web3-docs-mcp
pip install web3-docs-mcp
# or:
pipx install web3-docs-mcp
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"

web3-docs contract lookup demo

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.

web3-docs fork lookup demo

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:

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 for release history.

License

MIT — see LICENSE.

Available Tools

4 tools
list_fork_proposalsA

List every proposal activated by a named blockchain fork.

The unique value of this server: maps proposals → forks. Use this to answer "What's in Cancun?", "Which BIPs activated with Taproot?", "What does Shanghai include?" — anything that would otherwise require manually cross-referencing fork meta-EIPs.

Covers Ethereum forks (Frontier through Prague/Pectra) and Bitcoin soft-fork activations (P2SH, BIP66, CSV, SegWit, Taproot).

Args: fork_name: Fork name. Accepts canonical and consensus-layer aliases. Examples: "Cancun", "Dencun", "Shanghai", "Shapella", "Prague", "Pectra", "Paris", "The Merge", "Taproot", "SegWit", "London", "Berlin".

Inputs: fork_name (required). Returns: result

query_protocol_docsA

Read the specification of a blockchain protocol proposal.

Returns a compact metadata header plus the proposal body. When a query is provided, returns only the most relevant sections (saves tokens). Without a query, returns the full text (truncated to 4K chars — use a query to get specific sections of long proposals).

Args: proposal_id: Proposal ID from resolve_proposal. Examples: "eip-1559", "bip-341", "erc-20" query: Optional focus question. Examples: "base fee calculation", "security", "backwards compatibility"

Inputs: proposal_id (required), query. Returns: result

resolve_contractB

Look up canonical deployed contract addresses for Web3 protocols.

Covers: Uniswap, Aave, Compound, Curve, ENS, Lido, Maker, WETH, USDT, USDC, Multicall3, ERC-4337 EntryPoint, Gnosis Safe, Permit2, Seaport, 1inch, Across, Chainlink, CREATE2 Deployer. Multi-chain (Ethereum, Arbitrum, Base, Optimism, Polygon, etc.)

Args: protocol: Protocol name. Examples: "uniswap", "weth", "usdc", "aave", "safe" chain_id: Optional chain ID filter. "1"=Ethereum, "42161"=Arbitrum, "8453"=Base, "10"=Optimism, "137"=Polygon. Omit for all chains.

Inputs: protocol (required), chain_id. Returns: result

resolve_proposalA

Find blockchain protocol proposals by keyword, concept, or proposal number.

Searches across EIPs, ERCs, BIPs, SIMDs, Cosmos ADRs, Polkadot RFCs, Stacks SIPs, Avalanche ACPs, Cardano CIPs, Tezos TZIPs, Sui SIPs. Returns ranked results with fork info and status. Use the returned ID with query_protocol_docs to read the full spec.

Args: query: What to search for. Accepts concept names, keywords, proposal IDs, fork names, or opcode names. Examples: "fee market", "ERC-721", "taproot", "blob transactions", "PUSH0", "London fork", "CIP-25", "FA2 token", "sui object" chain: Optional chain filter for disambiguation. One of: ethereum, bitcoin, solana, cosmos, polkadot, stacks, avalanche, cardano, tezos, sui. Use when a keyword (e.g. "staking", "governance") could match multiple chains. Omit to search all.

Inputs: query (required), chain. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Web3 documentation: forks, proposal discovery, proposal reading, and contract addresses. No overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores (e.g., list_fork_proposals, resolve_proposal), making them predictable and easy to understand.

    Tool Count5/5

    Four tools is a compact yet complete set for the server's purpose—covering fork proposals, proposal search/reading, and contract resolution—without unnecessary bloat.

    Completeness5/5

    The tool surface covers the full workflow: find proposals (resolve_proposal), read them (query_protocol_docs), list fork contents (list_fork_proposals), and look up deployed contracts (resolve_contract). No obvious gaps for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      The open retrieval layer for AI agents. Index your entire project — code, docs, legal, research, data — and serve surgical context via MCP. FTS5 full-text search, optional semantic search (FastEmbed/ONNX), 10 built-in parsers, incremental auto-sync.
      8
      367 PyPI
      27
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Crypto-aware project memory for AI coding agents. Typed entities for Solana Programs/PDAs and EVM Contracts across Base, Optimism, Polygon, Arbitrum, Ethereum — plus chain-agnostic Decisions, Findings, and Integrations. Anchor + Hardhat auto-ingest, SQLite + FTS5 BM25 ranking, append-only versioning, git-aware diffs.
      46 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides intelligent code indexing with 15 MCP tools for symbol extraction, hybrid search (FTS5+vector), call graphs, and incremental indexing of local folders and remote repos, enabling token-efficient code retrieval for AI agents.
      3
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI coding agents to query a fully local SQLite FTS5 memory index of a codebase, returning high-density identity cards with exact line references, AST symbol contracts, phase maps, and colloquial intent search so agents can work without scanning raw files. It also supports incrementally syncing code changes and enriching knowledge under a six-pillar quality gate, keeping everything on-device with no cloud leakage.
      5
      MIT