tezos-mcp

RAG-powered MCP server for Tezos protocol specs, TZIPs, and Octez source code.

What It Does

Indexes and searches across:

• Octez Protocol - OCaml protocol implementations (src/proto_*/lib_protocol/)
• Octez Node - Shell architecture, RPC specs, P2P, storage (src/, docs/)
• TZIPs - Tezos Improvement Proposals (FA2, metadata, wallet standards)

Installation

# From PyPI
pip install tezos-mcp

# From source
pip install -e .

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

# With tree-sitter OCaml parsing
pip install -e ".[ocaml]"

Quick Start

# Build the index (downloads repos + creates embeddings)
tezos-mcp build

# Search
tezos-mcp search "FA2 token standard"

# Check status
tezos-mcp status

Features

Incremental Indexing

Only re-embeds changed files instead of rebuilding the entire index. Reduces update time from minutes to seconds.

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

# Incremental index (default behavior)
tezos-mcp index

# Force full rebuild
tezos-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
tezos-mcp models

# Use a specific model
tezos-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 ~/.tezos-mcp/config.yaml:

embedding_model: all-MiniLM-L6-v2
chunk_size: 1000
chunk_overlap: 200
protocol_depth: 3  # Number of past protocols to index

Expert Guidance

Curated knowledge beyond what's in the code:

# Via MCP tool
tez_expert_guidance("baking")
tez_expert_guidance("governance")
tez_expert_guidance("smart_rollups")

Topics include: baking, delegation, staking, tenderbake, governance, smart_rollups, dal, michelson, fa2, adaptive_issuance, slashing

CLI Commands

# Full build pipeline
tezos-mcp build                       # Download + compile + index
tezos-mcp build --full                # Force full rebuild

# Individual steps
tezos-mcp download                    # Clone octez + tzip repos
tezos-mcp compile                     # Parse OCaml/markdown into JSON
tezos-mcp index                       # Build vector embeddings
tezos-mcp index --full                # Force full rebuild
tezos-mcp index --model MODEL         # Use specific embedding model

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

# Search
tezos-mcp search "stake delegation"
tezos-mcp search "tenderbake consensus" --protocol paris
tezos-mcp search "FA2 transfer" --limit 10

# Lookup
tezos-mcp constant max_operations_ttl
tezos-mcp function apply_operation

# Info
tezos-mcp status                      # Index status, manifest info
tezos-mcp models                      # List embedding models
tezos-mcp serve                       # Start MCP server

MCP Tools

When running as an MCP server:

Tool	Purpose
tez_search	Semantic search across all indexed content
tez_search_tzip	Search TZIP standards (FA2, metadata, wallet specs)
tez_search_protocol	Search protocol specs and OCaml source
tez_search_octez	Search Octez node docs and source code
tez_grep_constant	Fast OCaml constant lookup
tez_analyze_function	Get OCaml function source code
tez_get_current_protocol	Current mainnet protocol (Tallinn)
tez_list_protocols	Full amendment history (Athens through Tallinn)
tez_expert_guidance	Curated guidance on Tezos topics

Protocol Amendments

Tezos upgrades through on-chain governance. The index covers the full amendment history:

Protocol	Date	Notable Features
Athens	2019-05	First amendment
Ithaca	2022-03	Tenderbake consensus
Mumbai	2023-03	Smart rollups
Paris	2024-06	Adaptive issuance, staking
Quebec	2025-02	Universal baker attestation
Tallinn	2026-01	6s block time

Project Structure

src/tezos_mcp/
├── server.py               # MCP server (FastMCP)
├── cli.py                  # CLI commands (Click)
├── config.py               # Configuration management
├── models.py               # Pydantic input validation
├── protocols.py            # Protocol amendment history
├── logging.py              # Structured logging
├── indexer/
│   ├── downloader.py       # Git clone with sparse checkout
│   ├── compiler.py         # Markdown/RST extraction
│   ├── ocaml_compiler.py   # OCaml parsing (tree-sitter + regex)
│   ├── chunker.py          # Document chunking + chunk IDs
│   ├── embedder.py         # Embeddings + LanceDB + incremental
│   └── manifest.py         # File tracking for incremental updates
└── expert/
    └── guidance.py         # Curated expert knowledge

Data Location

~/.tezos-mcp/
├── config.yaml             # Configuration (optional)
├── manifest.json           # Index state tracking
├── repos/
│   ├── tezos/              # Octez protocol + node (sparse checkout)
│   └── tzip/               # TZIP standards (full clone)
├── compiled/               # Extracted JSON specs
│   ├── tzips/
│   └── octez_docs/
└── lancedb/                # Vector index

Expert Guidance Topics

The tez_expert_guidance tool provides curated knowledge on:

Consensus & Baking:

• baking - Block production, endorsing, rights
• delegation - Delegating to bakers, rewards
• staking - Direct staking (Paris+), frozen deposits
• tenderbake - Deterministic finality consensus
• slashing - Double-baking/endorsing penalties

Governance & Standards:

• governance - On-chain amendment process
• fa2 - FA2 token standard (TZIP-012)
• michelson - Smart contract language

Scaling & Data:

• smart_rollups - L2 scaling (WASM rollups)
• dal - Data Availability Layer
• adaptive_issuance - Dynamic reward adjustment

Development

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=tezos_mcp

# Lint
ruff check src/

Running as MCP Server

# Start the server
tezos-mcp serve

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "tezos-mcp": {
      "command": "tezos-mcp",
      "args": ["serve"]
    }
  }
}

License

MIT