repo2graph
Use this MCP server to explore and query an indexed repository as a code graph with cited, budget-bounded results.
Map the repository:
repo_mapgives languages, hub files, and entry points, with a staleness warning if the index is out of date.Search code:
repo_searchruns BM25 lexical search expanded through graph neighbours and returns cited markdown blocks under a token budget, with optional paging.Traverse relationships:
repo_neighboursshows callers, callees, base classes, definitions, and tests reaching a symbol, with confidence filtering and JSON/co-change output.Resolve symbols:
repo_find_symbolfinds node IDs by name or file/line position for use in graph tools.Read cited source:
repo_readreturns a wider source window around a citation from indexed chunks, with secret paths excluded/redacted.Find connection paths:
repo_path_betweenfinds bounded paths between two nodes over call/definition/import edges and reports minimum confidence.Assess change impact:
repo_blast_radiusfinds reverse dependencies: callers of callers, subclasses, importers, and historically co-edited files.Diagnose server state:
repo_cache_statsreports cache metrics, andrepo_build_statuspolls asynchronous index-build progress.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@repo2graph Find the functions involved in user login and list their callers, callees, and neighbours."
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.
repo2graph
Cited, token-bounded answers about a codebase, for coding agents and CI.
Ask a repository a question and get back the source that answers it. Every block is headed
[cite: path:start-end], and the whole reply fits under a token ceiling that the tool enforces.
One tree-sitter pass records who calls whom, who imports what, and which files keep changing
together in git. Retrieval starts from BM25 matches and follows those links.
It needs no model, no API key, no language server and no database. Building, querying and the
MCP server make no network calls; the only exceptions are rag --answer (opt-in, sends the pack
to an LLM), repo2graph github and a rag/query target given as a GitHub spec (both clone a
repository), and --vectors/embed (download the embedding model on first use). Parsers are part of that promise:
tree-sitter-language-pack is pinned below 1.0 so every grammar arrives compiled into the
installed wheel, rather than being downloaded on first parse — see
SECURITY.md. Use it from the CLI, as an MCP server in Claude Code or Cursor, or as a GitHub Action.
Try it
uvx repo2graph demo # bundled example repo, five questions answered
uvx repo2graph build . -o .r2g # index your own code
uvx repo2graph rag "how does routing work" -o .r2g # a cited, budget-bounded context packGive an agent the same thing over MCP:
claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp .Cursor, Claude Desktop and other clients: docs/mcp.md. Step-by-step with expected
output: demo in docs/cli.md. What it produces on
thirteen well-known repositories — Django, FastAPI, React, Kubernetes, Linux and others, each at a
pinned commit with the command to reproduce it: examples/.
In VS Code, the extension in editors/vscode/ (a preview, built from
source) shows the callers, callees, base classes and co-changed files of the symbol at the cursor,
through the same MCP server.
Related MCP server: RepoGraph
Is it better than grep?
On cross-file structural questions, yes. On single-file lexical queries, no — grep is the
better tool. Both halves are measured on 40 lexical and 40 structural questions about Flask,
requests, FastAPI and Hono that repo2graph was not tuned against, scored against the
definitions that answer them, every retriever held to the same token budget
(method, full tables and diagnosis; raw rows in
results_holdout_final.json).
Where repo2graph wins: cross-file structural questions
grep structurally cannot traverse dependency edges, compute reverse call closures, or follow cross-module delegation. On questions whose evidence provably spans a cross-file graph edge:
Budget | repo2graph | lexical search alone | grep, then read around hits |
2,000 tokens | 29% | 24% | 14% |
4,000 tokens | 60% | 48% | 21% |
8,000 tokens | 79% | 55% | 38% |
The graph is what does it, and that is the comparison that matters: expansion adds +5/+12/+24 pp over the same retriever with expansion switched off. Against grep the margin is +15/+39/+41 pp — it widens with budget rather than closing, because grep has no edge to follow however much room it is given. It also gets there for fewer tokens than grep at every budget, by 7, 7 and 398 mean tokens, because a cited definition is a smaller thing to return than a window around every textual hit.
Where grep wins: single-file lexical questions
Budget | repo2graph | grep, then read around hits |
2,000 tokens | 17% | 28% |
4,000 tokens | 29% | 48% |
8,000 tokens | 45% | 59% |
On purely lexical questions where the evidence sits in a single file, text search is grep's
optimum, and this gap is real: −11/−19/−14 pp. We have not closed it. The remaining cause looks
like vocabulary mismatch rather than ranking — a question that says "datetime" does not match
code that says "timestamp" — which is why the
dense-vector path closes it to −2 pp at 8,000
tokens and more BM25 tuning has not. That path needs a downloaded model, so it is opt-in
(pip install "repo2graph[rag]") and the zero-dependency default stays the default.
That extra pulls PyTorch, which on Linux brings the NVIDIA CUDA wheels (several GB); the model is
fetched from Hugging Face on first use and its own licence and training data are yours to review
before you adopt it. Once it is cached, set HF_HUB_OFFLINE=1 so later runs make no request.
If that is too much to carry — on a CI runner, say — pip install "repo2graph[rag-static]" and
--embed-backend static get dense retrieval without torch: model2vec is a token→vector table
plus mean pooling, so inference is numpy, and it costs ~60 MB of packages and a ~31 MB model.
It is a different model (256-dim against 384), not a cheaper way to run the same one, so expect
it to retrieve differently — the figures above are the rag backend's. Pass the same
--embed-backend on the query side as you did to embed: the recorded model id is prefixed per
backend, so a mismatch is refused rather than silently fused.
Where repo2graph wins for agents: fewer turns
In simulated agent workflows (search → read → answer, via scripts/agent_eval.py). No
model is in the loop — the "agent" is a deterministic policy over real ripgrep and a real index:
Task set | Method | Success | Mean turns | Mean tokens | Precision per read |
Structural (40) | repo2graph | 40% | 1.9 | 2,590 | 12.0% |
Structural (40) | ripgrep | 10% | 2.5 | 586 | 29.0% |
Lexical (40) | repo2graph | 20% | 1.4 | 2,070 | 21.7% |
Lexical (40) | ripgrep | 18% | 3.0 | 740 | 89.1% |
Four times the structural success rate, and it reaches an answer in one or two turns where grep needs three. The turn count is the number that moved most — structural went 3.1 to 1.9 — because sharper seed ranking puts the answer in the first pack more often, and a turn saved is worth more to an agent than a token saved. It is not cheap: 4.4× grep's tokens on the structural set and 2.8× on the lexical one, and grep wins precision per read on both. repo2graph buys recall and turns with context; the budget-matched comparison is the single-shot tables above.
For completeness, the 35+10 question set this page used to report — visible since the first version of these tables and therefore a regression set, not evidence — now reads 44/63/80% lexical against grep's 35/61/72%, and 60/80/100% structural against grep's 20/20/70%. Those are the better-looking numbers, which is exactly why the held-out set is the one quoted above.
What it does do that grep doesn't:
Relationships in one hop.
repo_neighboursreturns a symbol's callers, callees, base classes and defining file, each with a line number. Every edge carries aconfidence: a name that could mean several definitions is markedambiguousand priced at1/n, not guessed.A hard ceiling. The pack is measured, clamped and re-measured before it's returned (12k tokens max over MCP), so an agent can't flood its own context through this tool.
Reverse closures from the graph.
repo_blast_radiuswalks what depends on a symbol, bounded by hop count and visit cap, with a citation per edge.
How it compares with Serena, Aider's repo map, CodeGraphContext, code-graph-rag, Sourcegraph, Cursor's index and Claude Code's own search, and with the dependency-graph tools Madge, dependency-cruiser and CodeSee, including when to use those instead: docs/comparison.md. Looking for a Sourcetrail alternative? It is not a drop-in replacement — there is no interactive desktop UI — and the comparison says what it does instead.
Five questions to start with
Ask your repo | What the graph adds |
| the guard itself, plus the routes that call it ( |
| CALLS edges into it, each with a confidence score |
| IMPORTS edges from the test module back to the code under test |
| the definition, then its direct callers from the CALLS edges into it (explain node) |
| the handler and its callees one hop at a time, each block cited to file and line |
GitHub Action
- uses: actions/checkout@v4
with: { fetch-depth: 0 } # full history, so CO_CHANGE edges are meaningful
- uses: Srinivasan-78/repo2graph@v5
with:
git-history: "500"
commit-branch: graph # optional: publish graph.html to a browsable branch@v5 follows every 5.x release; pin an exact tag (@v5.0.0) to upgrade by hand. The Action never
calls an LLM. Inputs and outputs: docs/cli.md.
Commands
Command | Does |
| Parse a repo into a graph and chunks ( |
| BM25 search plus one graph hop |
| Budget-bounded, cited context pack ( |
| Why an edge exists, or why a block was retrieved |
| Fetch, build and clean up without a local clone |
| Index a bundled example and answer the five questions above |
| Re-render |
| What changed structurally between two builds: symbols added, removed and renamed, edges, and whose callers changed |
| Diagnose setup, build a privacy-safe bug bundle, say why a path is (not) indexed, shell completion |
| stdio MCP server: |
Full flags: docs/cli.md. Python API: docs/python-api.md. Build cost up to 50,000 files: benchmarks/perf/README.md.
What it can't do
Resolve calls by type. Calls are matched by name, scoped by class, file, imports and directory.
x.get()on a receiver of unknown type is recorded as a low-confidence guess, not a fact. For exact references, use a language-server tool, or handbuild --scip index.scipa SCIP index (fromscip-python,scip-typescript, ...) to make the calls and bases it covers exact; see docs/architecture.md.See dynamic dispatch, reflection or computed imports. A missing edge doesn't prove that no call exists.
Cross language boundaries (Python calling C++ through bindings).
See a route that is registered by a call.
build --framework-edgeslinks decorator-declared routes to their handlers (FastAPI, Flask, Starlette, Sanic, NestJS) and adds a node per endpoint, soGET /users/{id}is a thing you can ask about. Express, Hono and Django'surlpatternsregister with a call instead —app.get("/x", handler)— where the handler is an argument and often an inline function, and those get no edge.
Symbols, calls and classes are extracted for Python, JS, TS, TSX, Go, Rust, Java, Ruby, C, C++,
C#, PHP, Kotlin, Swift, Scala, Bash, Lua, Objective-C and HCL (Terraform), plus the <script> blocks
of Vue and Svelte components and the code cells of Jupyter notebooks. Every other file is still
indexed as text. The
specific cases that defeat it — reflection dispatch, string-keyed registries, barrel re-exports —
are pinned as known failures in the
synthetic regression suite, and
per-language coverage is scored, unevenly, in
docs/architecture.md §4.
Two of those nineteen are benchmarked on real repositories: Python (Flask, requests, FastAPI) and TypeScript (Hono). Treat the rest as parsed-and-unmeasured. That is not a formality — the retrieval benchmark found two parse gaps in the one TypeScript repository as soon as it looked, one of which was hiding Hono's entire public API, and neither would have been visible without a real repository to ask questions about.
Status
The 3.x CLI, MCP tools and output schema follow semver. Default paths run locally, send no telemetry and exclude secrets from agent replies unconditionally (what never leaves your machine, how credential files are excluded, reporting a vulnerability). A Dockerfile for read-only, non-root local builds is provided (.github/SECURITY.md).
Platform & Environment Requirements
Environment | Status | Details |
Python | 3.11 – 3.14 | Tested across Linux, macOS, and Windows in CI (12 cells). Python 3.15+ is untested. Python 3.10 was supported through 4.1.0 and dropped in the next release, after it reached end of life in October 2026. |
Linux (glibc) | Supported (glibc ≥ 2.34) | Precompiled |
Legacy Linux | Unsupported wheels | RHEL 8, CentOS 8, Amazon Linux 2, Debian 11, and Ubuntu 20.04 ship glibc < 2.34. Wheels fail to load; use a glibc 2.34+ container or compile grammars from source. |
Alpine / musl | Unsupported wheels | Precompiled grammar wheels are not distributed for musl libc. Use a glibc container or build with a C toolchain. |
macOS / Windows | Fully supported | Tested on macOS 12+ (Apple Silicon & Intel) and Windows 10/11 (UTF-8 & CP1252 codepages). |
Run repo2graph doctor to diagnose environment and platform support.
Security & Maintenance Posture
Single maintainer: repo2graph is developed and maintained by a single author (@Srinivasan-78).
Automated gates: Pull requests must pass automated CI checks (ruff, mypy, multi-OS test matrix, synthetic regression benchmarks).
Review policy: Pull requests require 0 third-party review approvals to merge to
main.Commit signing: Commit signing is not currently enforced on
main.Integrity: Releases are published to PyPI with provenance attestations.
uv.lockpins every dependency by hash for CI and contributors (uv sync --frozen); a plainpip install repo2graphresolves its own versions within the ranges inpyproject.tomland does not read it.
Contributing
git clone https://github.com/Srinivasan-78/repo2graph && cd repo2graph
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
make lint format-check typecheck testBranch from develop. Start with .github/CONTRIBUTING.md and
docs/architecture.md. The most useful contribution right now is new
questions for the retrieval benchmark, especially on repositories
you know well. All docs: architecture, CLI,
MCP, Python API, comparison.
MIT licensed.
Available Tools
9 toolsrepo_blast_radiusAIdempotent
Reverse reachability from a node_id: callers of callers, subclasses of subclasses, importers of importers of its file, and historically co-edited files, by hop distance -- the blast radius of changing it. Read-only, deterministic, zero side effects, secret files excluded. When to use: use before editing a symbol to see what depends on it, or to answer 'what is the blast radius of changing X'. When NOT to use: do not use for open-ended search (use repo_search) or to read a symbol's own body (use repo_read). Output: JSON object with callers, subclasses, importers, cochange, and a summary.
Inputs: node_id (required), limit, max_hops, include_cochange.
repo_build_statusARead-onlyIdempotent
Query progress and status of a background index build task under --async-build. Read-only check of in-memory background worker. When to use: use when polling build progress after an async index build was started. When NOT to use: do not use when building synchronously or when queries already succeed. Once completed, use repo_search or repo_map to query code. Output: JSON object with task_id, status, parsed file progress, and error details.
Inputs: task_id (required).
repo_cache_statsAIdempotent
Retrieve runtime diagnostic counters for the tool result cache (hits, misses, size, max_size, ttl_s). Read-only, in-memory diagnostics, zero side effects. When to use: use when evaluating cache hit rate or debugging server performance. When NOT to use: do not use to search repository contents or inspect code structure; use repo_map or repo_search instead. Output: JSON object with cache metrics.
Inputs: no named parameters.
repo_find_symbolAIdempotent
Look up a symbol or file's node_id by name, or by path and line (the symbols enclosing that line, innermost first, then the file), for feeding into repo_neighbours, repo_read, repo_path_between or repo_blast_radius. Read-only, deterministic, zero side effects, secret files (.env) excluded. A name matches exactly first, then case-insensitively, then as a qualname's last segment; an ambiguous name returns every candidate, with its path. When to use: you know a name (from a traceback, a grep, a review comment) or a file position and want its node_id with no repo_search round trip. When NOT to use: not for open-ended text search (use repo_search) or for repo layout (use repo_map). Output: JSON array of {node_id, name, qualname, kind, path, start_line, end_line, lang}.
Inputs: kind, line, name, path, +2 more.
repo_mapAIdempotent
Retrieve a high-level structural map of the repository: languages, hub files, and top entry points. Read-only, deterministic, zero side effects. When to use: call this first at session start to understand codebase layout and identify entry points before detailed queries. Use when deciding where to investigate. When NOT to use: do not use to search code (use repo_search) or inspect call graphs (use repo_neighbours). Output: markdown summary of languages, hub files, and entry points, prefixed with a staleness note when the indexed working tree has changed since the index was built -- treat citations as suspect until rebuilt.
Inputs: no named parameters.
repo_neighboursAIdempotent
Traverse code graph relationships from a known symbol or file node_id (callers, callees, base classes, definitions). Read-only, deterministic traversal, no side effects. When to use: use with a specific node_id (e.g. from repo_search citations) to inspect callers (CALLS in), callees (CALLS out), inheritance, definitions, or the tests that reach a symbol through calls (TESTS in). When NOT to use: do not use for text search across code (use repo_search) or repo overview (use repo_map). Output: markdown list formatted as - <EDGE_TYPE> <in|out>: <name> (<path:line>) [<node_id>], or with format="json" the same rows as JSON plus co-changed files. To page past limit, pass cursor="" then each next_cursor: token from the reply's last line.
Inputs: node_id (required), hops, limit, cursor, +2 more.
repo_path_betweenAIdempotent
Find a bounded, bidirectional path between two node_ids over CALLS/DEFINES/IMPORTS edges (CO_CHANGE only if named explicitly), reporting the minimum confidence along each path. Read-only, deterministic traversal, no side effects. When to use: use for 'how does X reach Y' questions a text search cannot answer, e.g. the call chain from an HTTP handler to a database write. When NOT to use: do not use for one-hop neighbours (use repo_neighbours) or open-ended search (use repo_search). Output: JSON array of paths, each an ordered array of {node_id, path, start_line, end_line, via_edge, confidence}.
Inputs: to_id (required), from_id (required), max_hops, max_paths, +1 more.
repo_readAIdempotent
Read a widened window of source text around a citation, from the indexed chunks rather than the filesystem -- works with no shared filesystem between client and server, because chunks have already passed secret-path exclusion and redaction. Read-only, deterministic, zero side effects. When to use: use after repo_search or repo_neighbours to see more lines around a [cite: path:start-end] citation, with optional context lines each side. When NOT to use: do not use for a path never indexed, or an absolute or '..' path (both are refused); use repo_search or repo_find_symbol to find a valid path first. Output: [cite: path:start-end] header plus the text, bounded in size.
Inputs: path (required), context, end_line, start_line.
repo_searchAIdempotent
Search repository code for answers to questions using BM25 lexical ranking expanded with graph neighbours. Read-only, no side effects, secret files (.env) excluded. When to use: use for open-ended queries, locating implementations, or finding error strings. When NOT to use: do not use when you already have a symbol node_id and want callers/callees (use repo_neighbours); do not use for broad repo layout (use repo_map). Output: markdown citation blocks [cite: path:start-end] bounded by budget_tokens. To page, pass cursor="" then each next_cursor: token from the reply's last line.
Inputs: query (required), k, hops, cursor, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a sharply distinct purpose, and descriptions explicitly cross-reference alternatives with 'When NOT to use' clauses (e.g., repo_search vs repo_neighbours vs repo_map). Even the three graph-traversal tools (neighbours, blast_radius, path_between) are cleanly separated by scope (one-hop, reverse-reachability, bounded path).
All tools share a consistent `repo_` prefix and snake_case form, which is highly predictable. There is minor stylistic drift between verb-led names (repo_search, repo_read, repo_find_symbol) and noun-led names (repo_map, repo_neighbours, repo_path_between), but this stays readable and conventional.
Nine tools is well-scoped for a read-only code-graph navigation server, with each tool earning its place across discovery, traversal, reading, and diagnostics. No redundant or filler tools are present.
The surface covers discovery (map, search, find_symbol), inspection (read, neighbours), and impact analysis (blast_radius, path_between) plus operational status. Minor gaps exist, such as explicit file/directory listing, but core read-only navigation workflows are well covered.
Maintenance
Related MCP Connectors
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Repository knowledge graph MCP server for codebase understanding and debugging.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Related MCP Servers
- AlicenseBqualityBmaintenanceAn MCP code-intelligence server for AI agents with pre-indexed AST cache, 62 MCP tools, and TOON-compressed output, enabling token-efficient code analysis and project health grading entirely locally.9572 PyPI61MIT
- FlicenseNot gradedqualityCmaintenanceEnables coding agents to query a local-first code intelligence graph of Python repositories—covering functions, classes, modules, and their relationships—via MCP, supporting subgraph retrieval, caller lookup, and impact analysis without re-reading the codebase.-
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a local, multi-repo code graph for symbol exploration, blast radius analysis, co-change mining, and durable code-anchored memory via MCP tools.271 npm16Business Source 1.1
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to query an offline repository knowledge graph through MCP tools, including term lookup, shortest paths, node explanations, and cited LLM answers with file:line evidence.2MIT