How do I install Cgraphy?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Cgraphy need an API key?

No required environment variable is listed on this record.

What transport does Cgraphy use?

Cgraphy runs locally over stdio.

When was Cgraphy last checked?

Last checked 2026-11-10. Code knowledge graph over MCP: token-budgeted context for AI coding agents.

Cgraphy MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx cgraphy==0.1.1

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.pmgarg-cgraphy -- uvx cgraphy==0.1.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.pmgarg-cgraphy": {4      "command": "uvx",5      "args": [6        "cgraphy==0.1.1"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.1
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

cgraphy – 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_context expands the graph greedily around a symbol and stops exactly at your token budget — cost scales with the question, not the repo.
Git-aware. --git-history mines 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.md and AGENTS.md telling 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 index walks 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 serve exposes the five MCP tools over stdio.
Optional: --git-history adds weighted co-change edges mined from git 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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Cgraphy?

Does Cgraphy need an API key?

What transport does Cgraphy use?

When was Cgraphy last checked?

Documentation

cgraphy – Code Knowledge Graph MCP Server

Install

Quick start

The eight tools

Semantic search (optional)

Enriching the graph

Viewer

Measuring the savings

Localization benchmark (research harness)

How it works

Citing cgraphy

License