Standalone MCP server for codebase graph queries: tree-sitter parsing, SQLite persistence, AST + call-graph traversal.
- Node.js >= 20.0.0
This server is installed from GitHub (git), not the npm registry. The first install builds from source (tree-sitter and other native dependencies will compile).
# Step 1 — install globally from GitHub
npm install -g github:hesnotsoharry/codebase-graph-mcp
# Step 2 — register with Claude Code at user scope (cross-platform)
# macOS / Linux
claude mcp add --scope user codebase_graph node "$(npm root -g)/@hesnotsoharry/codebase-graph-mcp/dist/index.js"
# Windows (PowerShell)
claude mcp add --scope user codebase_graph node "$(npm root -g)\@hesnotsoharry\codebase-graph-mcp\dist\index.js"To pin a specific release tag, append #v0.3.0 to the install command:
npm install -g github:hesnotsoharry/codebase-graph-mcp#v0.3.0If you hit a ✗ Failed to connect error after registering, see Troubleshooting.
User scope (recommended — available in every Claude Code session on this machine):
# First, install globally from GitHub
npm install -g github:hesnotsoharry/codebase-graph-mcp
# Then register at user scope
# macOS / Linux
claude mcp add --scope user codebase_graph node "$(npm root -g)/@hesnotsoharry/codebase-graph-mcp/dist/index.js"
# Windows (PowerShell)
claude mcp add --scope user codebase_graph node "$(npm root -g)\@hesnotsoharry\codebase-graph-mcp\dist\index.js"Project scope (checked into repo; shared with collaborators via .claude/settings.json):
After installing globally (above), register at project scope:
# macOS / Linux
claude mcp add --scope project codebase_graph node "$(npm root -g)/@hesnotsoharry/codebase-graph-mcp/dist/index.js"
# Windows (PowerShell)
claude mcp add --scope project codebase_graph node "$(npm root -g)\@hesnotsoharry\codebase-graph-mcp\dist\index.js"Server-name convention: use
codebase_graph(underscore, not hyphen). Claude Code'sexecute_codecodemode accesses tools viaservers.<name>.<tool>— hyphens break JavaScript property access. The tools surface asmcp__codebase_graph__*in a Claude Code session.
claude mcp listExpected output:
codebase_graph: node C:\...\dist\index.js ✓ Connected
In any Claude Code session, ask Claude to list the available MCP tools — or call mcp__codebase_graph__ping to confirm the server is reachable. The full input schemas are returned when tools are introspected live; the table below gives one-line descriptions only.
Tools are grouped by category. For full input schemas, introspect via Claude Code's tool listing.
| Tool | Description |
|---|---|
list_projects |
List all indexed projects known to the graph database. |
delete_project |
Remove a project and all its graph data from the database. |
| Tool | Description |
|---|---|
index_repository |
Trigger a full or incremental index of the target repository. |
index_status |
Return the current index state: node count, last-indexed timestamp, staleness flag. |
ingest_traces |
Ingest externally-captured call traces to supplement AST-derived call edges. |
| Tool | Description |
|---|---|
search_graph |
Fuzzy symbol search over indexed nodes (functions, classes, interfaces, variables). |
search_code |
Regex-based text search across source files in the indexed repository. |
get_code_snippet |
Retrieve the source snippet and direct dependencies for a specific symbol ID. |
| Tool | Description |
|---|---|
trace_call_path |
BFS call-path between two symbol IDs — returns the shortest call chain. |
get_architecture |
High-level architectural view: hotspots, module clusters, file tree summary. |
detect_changes |
Files and symbols changed since the last index run. |
| Tool | Description |
|---|---|
get_graph_schema |
Return the graph's node labels, edge types, and property keys. |
query_graph |
Execute a simplified Cypher-subset query against the graph database. |
| Tool | Description |
|---|---|
manage_adr |
Create, list, or retrieve Architecture Decision Records stored alongside the project. |
| Tool | Description |
|---|---|
ping |
Health check — returns pong. Use to verify the server is connected and responding. |
The server detects the project root from its working directory at startup. An explicit index_repository call is currently required before queries return meaningful results — the server does not auto-index on first query. Lazy auto-init (index on first non-ping query if the project is cold) is on the roadmap for v0.2.0; track it at GitHub Issues.
Graph data is persisted at:
~/.codebase-graph/<project-hash>/graph.db
If you have an existing ~/.ouroboros-graph/ directory from v0.1.0, the server migrates it automatically on the first run of v0.2.0 — no manual steps needed.
After the initial index, the server watches for file changes via @parcel/watcher and triggers incremental reindex automatically. You only need to call index_repository explicitly for the first index or after a major structural change (e.g., a large branch merge).
The server exposes a non-MCP CLI mode for hook-driven background indexing:
node dist/index.js --reindex-if-stale <rootPath>Behaviour:
- Resolves the graph DB for
<rootPath>(same hash as the running server would use). - Checks staleness: runs an incremental index if the project has no record, or if the repository's last-change timestamp (from
git log -1 --format=%ct; falls back to max file mtime) is newer thanindexed_at. - If fresh: exits 0 silently.
- Every failure path: logs one line to stderr and exits 0 — safe to spawn fire-and-forget from a
SessionStarthook without blocking the session. - Never starts the MCP transport — this mode is exit-only.
Typical invocation from a Claude Code SessionStart hook:
{
"hooks": {
"SessionStart": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "node /path/to/dist/index.js --reindex-if-stale ${cwd}"
}]
}]
}
}Ensure the package is installed globally and the path is correct:
npm install -g github:hesnotsoharry/codebase-graph-mcp
claude mcp add --scope user codebase_graph node "$(npm root -g)\@hesnotsoharry\codebase-graph-mcp\dist\index.js"Verify the path exists with:
Test-Path "$(npm root -g)\@hesnotsoharry\codebase-graph-mcp\dist\index.js"If this still fails, file an issue using the Windows registration failure template — it prompts for the diagnostics needed to triage the specific failure.
The server is connected but the project has not been indexed yet. Call index_repository first:
mcp__codebase_graph__index_repository
Then verify with index_status — look for a non-zero node count.
The server did not start successfully. Check claude mcp list — if the status is not ✓ Connected, the server process exited before the tool handshake completed.
Common causes:
- Wrong path to
dist/index.js(verify the file exists at the registered path) - Node version below 20 (
node --versionmust be>= 20.0.0) - Permission denied on the database directory (
~/.codebase-graph/must be writable)
The package requires Node >= 20. Confirm with:
node --versionIf you have multiple Node versions installed (via nvm, volta, or nvm-windows), ensure the version Claude Code inherits from your environment is >= 20. The MCP server is started with the Node that is in PATH at Claude Code launch time — not the version active in your current terminal.
After registration, run:
claude mcp listExpected output (Windows shown; Linux/macOS path differs):
codebase_graph: node C:\Users\YOU\AppData\Roaming\npm\node_modules\@hesnotsoharry\codebase-graph-mcp\dist\index.js ✓ Connected
Tools surface as mcp__codebase_graph__* in Claude Code sessions (underscore namespace, not hyphen — JavaScript object-key compatibility).
To update to the latest version from GitHub:
npm install -g github:hesnotsoharry/codebase-graph-mcpTo pin a specific release tag:
npm install -g github:hesnotsoharry/codebase-graph-mcp#v0.3.0Claude Code will automatically reconnect to the server on the next session.
Diagnostic logs are written to stderr only. The server never writes to stdout — stdout is reserved for the MCP JSON-RPC protocol stream. Any console.log to stdout would corrupt the protocol and break the connection.
Look for [trace:graph-mcp.*] prefixed lines in stderr when debugging.
See CONTRIBUTING.md for the issue policy, PR workflow, and solo-maintenance notes.
MIT — Copyright (c) 2026 Cole Stacey