cgraphy MCP server
✓ VerifiedIndexes codebases into a knowledge graph to provide token-budgeted context and structural insights for AI coding agents.
Also known as pmgarg/cgraphy
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- 87
- Latest version
- 0.1.1
- Last commit
- Jul 18, 2026
- License
- MIT
What is cgraphy MCP?
cgraphy indexes codebases into a knowledge graph to provide token-budgeted context and structural insights for AI coding agents. It exposes 8 tools, such as cgraphy_overview, cgraphy_search, cgraphy_context.
Summary generated from the project's README
About cgraphy MCP server
Indexing codebases into a structured knowledge graph to provide token-budgeted context is what cgraphy enables for AI coding agents. Instead of forcing an assistant to read entire files to understand a project, this server provides compact subgraphs containing functions, classes, and files. It is designed for developers using tools like Claude Code, Cursor, Gemini CLI, or Codex CLI to navigate large repositories without exhausting context windows.
The system works locally using a single SQLite file and requires no external services or vector databases. It supports high-fidelity extraction for languages including Python, TypeScript, Java, Go, C, C++, and Rust, while using tree-sitter for over 20 additional languages. Users can initialize their project with a single command to set up the index and agent steering instructions.
Key features include PageRank to identify important symbols and git-aware analysis to find files that change together. The cgraphy_context tool expands the graph around a specific symbol and stops exactly at a defined token budget. For more advanced needs, an optional semantic search can be installed to bridge the gap between natural language queries and code identifiers.
What you can do with it
- 1Retrieving context within token limitsAn agent can fetch a relevant subgraph around a specific symbol while staying within a strict token budget.
Written from the project's README. Every use case is checked against a quote from it.
How to install cgraphy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall cgraphy MCP in Claude Code
$ claude mcp add cgraphy -- uvx cgraphyInstall cgraphy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cgraphy": {
"command": "uvx",
"args": [
"cgraphy"
]
}
}
}Install cgraphy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cgraphy": {
"type": "stdio",
"command": "uvx",
"args": [
"cgraphy"
]
}
}
}Install cgraphy MCP in VS Code CLI
$ code --add-mcp '{"name":"cgraphy","type":"stdio","command":"uvx","args":["cgraphy"]}'Install cgraphy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cgraphy": {
"command": "uvx",
"args": [
"cgraphy"
]
}
}
}Install cgraphy MCP in Codex
$ codex mcp add cgraphy -- uvx cgraphyInstall cgraphy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cgraphy] command = "uvx" args = ["cgraphy"]
Install cgraphy MCP in Gemini CLI
$ gemini mcp add -s user cgraphy uvx -- cgraphyInstall cgraphy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cgraphy": {
"command": "uvx",
"args": [
"cgraphy"
]
}
}
}cgraphy MCP tools 8
Detected from the READMEcgraphy_overviewcgraphy_searchcgraphy_contextcgraphy_readcgraphy_impactcgraphy_diff_contextcgraphy_enrichcgraphy_store_summaries
| cgraphy_overview | — | |
| cgraphy_search | — | |
| cgraphy_context | — | |
| cgraphy_read | — | |
| cgraphy_impact | — | |
| cgraphy_diff_context | — | |
| cgraphy_enrich | — | |
| cgraphy_store_summaries | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablepmgarg/cgraphy is public and reachablegithub.com/pmgarg/cgraphy ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-18github.com/pmgarg/cgraphy ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from cgraphyPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcgraphy – Code Knowledge Graph MCP Server
Paper (DOI): https://doi.org/10.5281/zenodo.21422935
PyPI: https://pypi.org/project/cgraphy/
GitHub: https://github.com/pmgarg/cgraphy
cgraphy is a Python code knowledge graph and Model Context Protocol (MCP) server for AI coding agents such as Claude Code, Codex CLI, Cursor, and Gemini CLI.
cgraphy indexes any codebase into a knowledge graph — functions, classes and files as nodes; calls, imports, inheritance and git co-change history as edges — and serves compact, token-budgeted slices of it to AI assistants through the Model Context Protocol. Instead of re-reading dozens of files to orient itself on every prompt, an agent asks the graph and gets the relevant subgraph in a couple of thousand tokens.
- Any language. Full-fidelity extraction (calls, imports, inheritance) for Python, TypeScript/JavaScript, Java, Go, C, C++ and Rust; generic definition-level extraction for 20+ more via tree-sitter; config and docs files participate through summaries.
- Importance-ranked. PageRank over the code graph puts load-bearing symbols first in every answer.
- Token-budgeted.
cgraphy_contextexpands the graph greedily around a symbol and stops exactly at your token budget — cost scales with the question, not the repo. - Git-aware.
--git-historymines commit history for files that change together (logical coupling), an edge type static analysis can't see. - No API key. Semantic summaries are written by the host agent itself through the enrich loop; summaries survive re-indexing via content hashing.
- Zero infrastructure. One SQLite file in
.cgraphy/. No services, no daemons, no vector database. - Proven end-to-end. In 400+ controlled agent runs on SWE-bench Lite, the deployed configuration resolved 14 vs 8 of 57 real GitHub issues (official Docker harness). Indexes kubernetes (26K files, 219K nodes) in 49s, keeps it fresh in 1.6s cycles, answers queries in 1–152ms. All benchmarks and predictions are in this repo (Research paper and benchmarks).
Install
pip install cgraphy # or: uv tool install cgraphy
Quick start
cd your-repo
cgraphy init # one command: MCP config + agent steering + index
cgraphy init does three things:
- Writes a project-scoped
.mcp.json— picked up automatically by Claude Code in all its forms: CLI, VSCode extension, and the desktop app. - Appends a steering block to
CLAUDE.mdandAGENTS.mdtelling agents to consult the graph (cgraphy_overview→cgraphy_search→cgraphy_context) before reading files — this is what makes the graph actually replace bulk file reading. (Agents can't be forced, only steered: instruction files + persuasive tool descriptions + the tools being genuinely faster is the mechanism, and it works.) - Builds the index with git co-change history.
Or register the MCP server manually with your assistant:
Claude Code
claude mcp add cgraphy -- uvx cgraphy serve /path/to/repo
Codex CLI (~/.codex/config.toml)
[mcp_servers.cgraphy]
command = "uvx"
args = ["cgraphy", "serve", "/path/to/repo"]
Gemini CLI (~/.gemini/settings.json) / Cursor (.cursor/mcp.json)
{"mcpServers": {"cgraphy": {"command": "uvx",
"args": ["cgraphy", "serve", "/path/to/repo"]}}}
The eight tools
Reading / orientation:
| Tool | Returns | The agent uses it… |
|---|---|---|
cgraphy_overview |
Repo map: subsystems, key symbols by importance, all files | first, instead of reading files to orient |
cgraphy_search |
Ranked matches with file:line and summaries (hybrid lexical+semantic when the [semantic] extra is installed) |
before grep / directory listing |
cgraphy_context |
Subgraph around a symbol (callers, callees, imports, co-changes) within a token budget | instead of reading whole files |
cgraphy_read |
Just one symbol's source, line-numbered, budgeted | instead of reading the whole file |
Editing / reviewing — the tools that make the graph part of the change loop:
| Tool | Returns | The agent uses it… |
|---|---|---|
cgraphy_impact |
Blast radius: direct + transitive dependents, affected tests, historically co-changed files | before modifying shared code |
cgraphy_diff_context |
The working git diff mapped to touched symbols, their users, and covering tests | before committing / when resuming work |
Enrichment:
| Tool | Returns | The agent uses it… |
|---|---|---|
cgraphy_enrich |
Batch of symbols that still need one-line summaries | when asked to "enrich the graph" |
cgraphy_store_summaries |
Confirmation + remaining count | to save the summaries it wrote |
Retrieval is usage-aware: symbols an agent repeatedly asks about get a small, capped boost in future context expansion (telemetry stays in the local SQLite file; nothing leaves your machine).
Semantic search (optional)
pip install "cgraphy[semantic]"
Adds tiny static embeddings (model2vec, CPU-only, no torch) fused with FTS5
by reciprocal-rank fusion — closes the vocabulary gap between issue-style
prose ("login broken") and code identifiers (validate_jwt).
The graph self-heals: tools detect stale files and re-index incrementally (changed files only) before answering.
Enriching the graph
Structure is extracted automatically; meaning comes from summaries. Tell your agent once:
enrich the cgraphy graph
It will loop cgraphy_enrich → cgraphy_store_summaries until every symbol
has a one-line semantic summary. Summaries are keyed to a hash of each
symbol's source, so editing one function invalidates only that summary.
For CI, cgraphy index --summarize pre-bakes summaries with your own
Anthropic API key (pip install cgraphy[summarize], ANTHROPIC_API_KEY set).
Viewer
cgraphy view . # http://localhost:8787
A dependency-free local page (bundled Cytoscape.js): search, color by kind, click for details, double-click to expand neighbors; co-change edges shown dashed.
Measuring the savings
python scripts/benchmark.py /path/to/repo "your question"
Prints the tokens an agent spends orienting via cgraphy (overview + search + context) versus reading every code file, and the reduction factor.
Localization benchmark (research harness)
python scripts/eval_localization.py /path/to/repo 50
Mines fix-like commits from the repo's history (subject = query, touched files = ground truth, co-change mining excludes evaluated commits), then scores an ablation ladder — FTS-only, +PageRank, +graph expansion, ±co-change edges — on hit@5/hit@10/MRR and token cost. No LLM calls, no human grading, fully reproducible. Results and a paper draft live in paper/.
How it works
cgraphy indexwalks the repo (respecting.gitignore+.cgraphyignore), parses each file with tree-sitter, and stores nodes and edges in.cgraphy/graph.db(SQLite + FTS5). Re-indexing is incremental by content hash.- A resolver links cross-file references (calls, imports, inheritance) by qualified name, best-effort; unresolved names are kept, never dropped.
- PageRank runs over the edge graph; every query surfaces important symbols first. Search blends FTS5 relevance with rank.
cgraphy serveexposes the five MCP tools over stdio.- Optional:
--git-historyadds weighted co-change edges mined fromgit log.
Design details: docs/superpowers/specs/2026-07-08-cgraphy-design.md
Citing cgraphy
If you use cgraphy in research or tooling, please cite the paper:
@misc{garg2026cgraphy,
author = {Garg, Prateek Mohan},
title = {Which Graph Signals Pay for Their Tokens? cgraphy: A Token-Budgeted
Code Knowledge Graph as a Portable Context Layer for AI Coding Agents},
year = {2026},
doi = {10.5281/zenodo.21422935},
url = {https://doi.org/10.5281/zenodo.21422935},
note = {Preprint}
}
License
MIT
mcp-name: io.github.pmgarg/cgraphy
cgraphy MCP questions
How do I add cgraphy MCP to Claude Code?
Run claude mcp add cgraphy -- uvx cgraphy in your terminal. Add --scope user to make it available in every project.
How do I add cgraphy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does cgraphy MCP provide?
It exposes 8 tools, including cgraphy_overview, cgraphy_search, cgraphy_context, cgraphy_read, cgraphy_impact.
What languages does cgraphy support?
It provides full-fidelity extraction for Python, TypeScript/JavaScript, Java, Go, C, C++, and Rust, plus generic extraction for over 20 more languages via tree-sitter.
Does cgraphy require an external database or API key?
No, it uses a local SQLite file for storage and requires no API keys for basic operation, as semantic summaries are written by the host agent.
How does cgraphy help manage token usage?
It uses a token-budgeted context expansion that grows around a symbol and stops exactly at your specified budget.
Can cgraphy use git history to understand code?
Yes, it can mine commit history to identify files that change together, creating logical coupling edges.
How do I install cgraphy?
You can install it via pip using pip install cgraphy or via uv using uv tool install cgraphy.