How do I use tezos-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tezos-mcp How does adaptive issuance work?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tezos-mcp

by dmichael

Overview Schema Source Related Servers Discussions Admin

Python

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)

Related MCP server: mcp-rag-server

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

Available Tools

9 tools

tez_analyze_functionTez Analyze FunctionB

Extract an OCaml function implementation from the protocol source.

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

tez_expert_guidanceTez Expert GuidanceB

Get curated expert knowledge about a Tezos topic.

Available topics: baking, delegation, staking, tenderbake, governance, smart_rollups, dal, michelson, fa2, adaptive_issuance, slashing

Inputs: topic (required). Returns: result

tez_get_current_protocolTez Get Current ProtocolA

Get the current Tezos mainnet protocol name, number, and features.

Inputs: no named parameters. Returns: object

tez_grep_constantTez Grep ConstantA

Look up an OCaml constant definition from the protocol source.

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

tez_list_protocolsTez List ProtocolsA

List all Tezos protocol amendments in chronological order.

Inputs: no named parameters. Returns: result

tez_searchTez SearchA

Cross-source semantic search across Tezos documentation, TZIPs, and protocol source.

Inputs: query (required), limit, protocol. Returns: result

tez_search_octezTez Search OctezB

Search Octez node documentation and source code.

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

tez_search_protocolTez Search ProtocolB

Search protocol specifications and OCaml source code.

Inputs: query (required), limit, protocol. Returns: result

tez_search_tzipTez Search TzipA

Search TZIP standards (token standards, metadata specs, wallet standards).

Inputs: query (required), limit, tzip_number. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-09-07 02:40 across 9 tools

Disambiguation4/5

Most tools have distinct purposes, though the four search variants (tez_search, tez_search_tzip, tez_search_protocol, tez_search_octet) are closely related and could be confused if users don't read descriptions carefully. However, each targets a specific source, reducing ambiguity.

Naming Consistency5/5

All tools follow the consistent 'tez_' prefix with a verb_noun pattern (e.g., search, grep, analyze, get, list). This uniformity makes the toolkit predictable and easy to navigate.

Tool Count5/5

With 9 tools, the set is well-scoped for a Tezos protocol assistant. It covers searching, specific lookups, and expert guidance without being overwhelming or sparse.

Completeness4/5

The tools cover core needs: general and targeted search, constant/function extraction, protocol info, and expert knowledge. Minor gaps like broader CRUD operations or editing are absent, but this fits the read-only analytical intent of the server.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mcpA
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
https://llmse.ai/mcp
H-IndexA
ai.xr-utilities
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Search Documentation Access
2
https://h-index.xr-utilities.ai/mcp
forkast-mcp-docsA
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42
https://mcp.forkast.gg/mcp
SynaplanA
io.github.metadist
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
RAG Systems Knowledge & Memory AI & Machine Learning
101921
https://web.synaplan.com/mcp

Related MCP Servers

ragi
RAG Systems Search
SusuTawar
A
license
A
quality
D
maintenance
Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
Updated 3 months ago (2026-08-13 16:07 UTC)
3
8 npm
MIT
mcp-rag-server
RAG Systems Search
kwanLeeFrmVi
A
license
Not graded
quality
D
maintenance
An MCP server that indexes documents and serves relevant context to LLMs via Retrieval Augmented Generation (RAG).
Updated 2 years ago (2025-04-18 17:10 UTC)
35 npm
36
MIT
rag-mcp
RAG Systems Search
Ma-fee
F
license
Not graded
quality
D
maintenance
A RAG service based on FastMCP that enables document indexing and retrieval (keyword/vector search) through the MCP protocol.
Updated 7 months ago (2026-04-14 14:12 UTC)
-
knowledge-mcp
RAG Systems Vector Databases Knowledge & Memory
yungsimeon
A
license
Not graded
quality
D
maintenance
An MCP server that enables semantic search over a private knowledge base via pgvector, with GitHub OAuth authentication and a RAG pipeline.
Updated 4 months ago (2026-07-14 09:25 UTC)
23 npm
MIT

tezos-mcp

What It Does

Installation

Quick Start

Features

Incremental Indexing

Configurable Embedding Models

Expert Guidance

CLI Commands

MCP Tools

Protocol Amendments

Project Structure

Data Location

Expert Guidance Topics

Development

Running as MCP Server

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

ragi

mcp-rag-server

rag-mcp

knowledge-mcp