codegraph-mcp

A knowledge graph of your code, served to any LLM over the Model Context Protocol.

codegraph-mcp clones a Git repository, parses it into a Neo4j dependency graph (Repository → File → Function, linked by CONTAINS / DEFINES / IMPORTS / CALLS), and exposes that graph as read-only MCP tools. An agent can then answer "what breaks if I change auth_service.py?" by traversing edges — one structured query instead of re-reading the repo into its context window every session.

It ships with a browser UI that renders the same graph as a layered architecture map, so the graph is useful to you as well as to the model.

Contents

• How it works · Quick start · Ingest a repo

• Connect an MCP host · MCP tools · CLI

• Web UI · Private repositories

• Configuration · Troubleshooting

Related MCP server: revibe-mcp

How it works

Three phases, deliberately split across two processes:

Why the split. All the slow, risky work (network, disk, parsing) lives in the offline phase, so the server stays sandboxed and fast — no clone timeouts, no write path to abuse.

Repo isolation. Every node and edge carries a graph_id, and every Cypher statement filters on it. Many repos share one database with no cross-talk, and it's a server-side guarantee rather than client trust. The graph_id is host-qualified (github.com/owner/name), so the same owner/name on GitHub and on an internal GitLab stay separate graphs.

An honest graph. Imports that resolve outside the repo (stdlib, npm packages) become lightweight Symbol leaves instead of phantom files. Re-ingestion is idempotent — nodes are upserted with MERGE, and files deleted from the tree are tombstoned rather than hard-deleted.

Languages. Python (stdlib ast); JavaScript, TypeScript, TSX/JSX, Java, and Kotlin (tree-sitter). Adding one more means adding a row to src/codegraph/ingestion/languages.py plus a parser and an import resolver.

Quick start

Requires Python 3.11+, uv, and Docker.

git clone <codegraph-mcp> && cd codegraph-mcp
uv sync --extra dev          # all deps pinned via uv.lock
cp .env.example .env
docker compose up -d         # Neo4j on bolt://localhost:7687
uv run pytest -m "not slow and not integration"

Ingest a repo

uv run codegraph ingest https://github.com/<owner>/<name>
# → {"graph_id": "github.com/owner/name", "files": 142, "functions": 880, ...}

uv run codegraph ls          # what's in the graph so far

Connect an MCP host

Point the host at the project directory; it spawns the server over stdio.

{
  "mcpServers": {
    "codegraph": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\codegraph-mcp", "codegraph", "serve"]
    }
  }
}

{
  "mcpServers": {
    "codegraph": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codegraph-mcp", "codegraph", "serve"]
    }
  }
}

{
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/codegraph-mcp", "codegraph", "serve"]
    }
  }
}

No host handy? Drive it with the MCP Inspector:

uv run mcp dev src/codegraph/server.py

MCP tools

All tools are read-only and scoped by graph_id.

Two resources ground the model at session start: codegraph://repos (everything ingested) and codegraph://schema/{graph_id} (label and edge breakdown for one repo).

Errors are written for an LLM to recover from: bad arguments surface as JSON-RPC -32602, and business errors (unknown repo, missing file) return isError: true with plain-text guidance on what to try next.

CLI

A Makefile wraps the common loops: make dev, make up, make test, make lint, make typecheck, make viz.

Web UI (codegraph viz)

A read-only browser view of the same graph the MCP tools query. It runs as its own process, so the MCP server's stdout stays pure JSON-RPC.

make up                                            # Neo4j
uv run codegraph ingest https://github.com/owner/name
make viz-build                                     # one-time, needs Node 18+
make viz                                           # → http://127.0.0.1:8787

Skip viz-build and the API still serves — / just returns a hint to build the frontend.

The layout carries meaning. The default view is an architecture map, not a force-directed hairball: a node's row is its dependency depth (entry points on top, leaves at the bottom) and its size is how many files depend on it. Within a row, nodes are ordered to minimise edge crossings — a barycenter sweep plus a transpose refinement, as in Sugiyama layered drawing — which measured 60% fewer crossings than ordering rows by path.

The Findings panel answers the questions you actually ask of an unfamiliar codebase. Each finding is clickable and highlights on the canvas.

Plus search, click-to-highlight a neighbourhood (outgoing blue, incoming orange), particle flow along a hovered file's edges, a minimap, a detail panel with source and per-file imports/dependents/functions, and blast radius for a change. Change coupling reads the on-disk clone's git log; everything else is graph structure.

Development (hot reload) is two processes:

make viz-dev                 # terminal 1 — API on :8787
cd vizui && npm run dev      # terminal 2 — Vite on :5173, proxies /api

Private repositories

Cloning a private repo needs credentials. In order of preference:

1. SSH keys or your OS credential helper — nothing to configure. Ingestion shells out to git, which inherits your environment: if git clone works in your terminal it works here. Use an SSH URL (git@github.com:owner/name.git) or let the credential manager answer.

2. GIT_TOKEN — for headless/CI, where no ambient credentials exist:

GIT_TOKEN=<personal-access-token> uv run codegraph ingest https://github.com/owner/private

The token is injected only for the duration of the network call; origin is immediately rewritten to a credential-free URL, so nothing is left in .git/config. The URL stored in Neo4j and every failure message are sanitized, so a token never reaches the graph or your logs.

Configuration

Copy .env.example to .env. Every value has a working default.

Troubleshooting

uv run fails with failed to remove file ... codegraph.exe ... used by another process. A running codegraph serve (spawned by your MCP host) is holding the entry point while uv tries to replace it after a dependency change. Either skip the reinstall:

uv run --no-sync codegraph viz

…or fix it once: stop the MCP server (on Windows, tasklist | findstr codegraph then Stop-Process -Id <pid>), run uv sync --extra dev, and let the host respawn it.

Tech stack

Python 3.11+, mcp>=1.27,<2 (FastMCP), Neo4j 5.x, pydantic v2, tree-sitter, GitPython, uv — with pytest, ruff, and mypy on the dev side. The web UI adds FastAPI + uvicorn on the backend and Vite + React + Cytoscape.js on the frontend.

Project status

v0.1 — stdio transport, Neo4j 5.x backend, nine read-only tools, six languages.

Further reading

• CONTRIBUTING.md — architecture, hard conventions, testing strategy, CI gates

• PROJECT_OVERVIEW.md — the problem, the design, and why it's shaped this way

• docs/data-flow-explainer.md — how a request travels through the system

License

MIT.