codegraph-mcp

Intent search over your Python repo's call graph, inside Cursor. One MCP tool returns cite spans and caller→anchor→callee chains so the agent searches once, reads surgically, and burns fewer tokens than grep-then-read loops.

Demo

Related MCP server: repo-memory-mcp

Requirements

All of the following are required:

Hardware: ~8 GB RAM recommended; ~3–5 GB disk for models after first run.

Scope: Python repositories only (for now).

Quick start

# 1. Ollama + required model
brew install ollama          # or https://ollama.com
ollama pull qwen2.5:1.5b

# 2. Install codegraph-mcp (once)
python -m venv .venv
source .venv/bin/activate
pip install "git+https://github.com/SahilSheikh12299/codegraph-mcp.git"

# 3. Global setup (once)
codegraph-mcp setup

Then restart Cursor (or reload MCP in Settings → MCP).

Open any Python repo and ask Cursor where behavior lives — e.g. "Where is authentication handled?" The first search indexes that repo; later searches use the cache at ~/.cursor_graph_rag/graphs/.

No per-project configuration needed.

Pinned install

pip install "git+https://github.com/SahilSheikh12299/codegraph-mcp.git@v0.1.0"

Usage

The MCP server exposes one tool:

search_codebase_intent

search_codebase_intent(
    search_queries=["how redirects are resolved after HTTP response"],
    active_project_root="/absolute/path/to/repo",
    grep_terms=["resolve_redirects"],  # optional symbol anchors
)

Returns markdown with up to 2 matches per grep term and per search query: anchor cite, a tiny call flow, and caller/callee cites. The agent reads those line ranges with native Read — no full-file dumps.

active_project_root is the absolute workspace root (Cursor provides this in context).

What setup does

codegraph-mcp setup runs once globally:

1. Verifies Ollama is running and qwen2.5:1.5b is installed

2. Prefetches HuggingFace embedding + reranker models (warns if offline)

3. Merges codegraph-mcp into ~/.cursor/mcp.json

4. Installs agent skill at ~/.cursor/skills/codegraph-mcp/SKILL.md

Performance expectations

Why searches aren't instant: Each search_codebase_intent call syncs the graph for that workspace, then searches. That keeps results fresh but means the tool is "sync then search," not a pure in-memory lookup.

Model memory: Embedding and reranker models unload after each tool call to keep RAM down. The next search pays load cost again (~few seconds on CPU, faster with GPU). Concurrent overlapping calls share one loaded instance.

Rough repo sizing (first index, CPU, Ollama docstrings on):

Disable auto-docstrings during indexing if you only want speed over semantic richness:

export CURSOR_GRAPHRAG_AUTO_DOCSTRINGS=0

Known limitations (v0.1)

• Python only — .py source files; no JS, Go, notebooks as first-class targets.

• Static call graph — CALLS edges come from AST name resolution + import tracking. Dynamic dispatch (getattr, eval, heavy metaprogramming) may be missing or incomplete.

• Cursor + MCP — Tested around Cursor's MCP workflow and agent skill; other MCP hosts may work but aren't the primary target.

• Agent discipline — The skill guides "one search, surgical reads," but the host model can still grep or over-read if it ignores the skill.

• Top-2 per term — Returns at most two matches per grep term and per intent query by design (token budget). Obscure symbols may need a refined query or grep_terms.

• Local stack required — Ollama + HuggingFace models; not a hosted/API-only product.

• Single global MCP process — One Python env serves all workspaces; model weights install once in that venv.

Documentation

• Installation guide

• Configuration

• Architecture

Development

git clone https://github.com/SahilSheikh12299/codegraph-mcp.git
cd codegraph-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.