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:

Tracks file hashes and modification times in a manifest
Detects which files changed since last index
Only re-embeds the changed content
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