CodeGraph MCP Server

Cross-language code intelligence for AI agents — 42 tools, 38 languages, persistent memory, documentation intelligence, one-call PR review.

Install

npm install -g @astudioplus/codegraph-mcp

The analysis engine is not bundled in the package. Install downloads the engine built for your platform from its GitHub release - tagged with the engine's version, which an npm-only patch release does not move - and verifies it against the published .sha256 before installing it (on Windows the ONNX Runtime sidecar comes with it).

A failed download never fails the install, because the CLI, the hooks and the docs all still work - it prints a warning instead. Retry it with:

npx codegraph-mcp-fetch-engine          # --force re-downloads an engine that is already present

For air-gapped machines, or if you vendor the binary yourself, set CODEGRAPH_SKIP_BINARY_FETCH=1 to skip the download and supply the engine one of two ways:

• place it at <package>/bin/codegraph-server-<platform>-<arch> (.exe on Windows) - the path codegraph-mcp launches by default; or
• point CODEGRAPH_SERVER_PATH at the engine wherever it already lives. This wins over the bundled path, and codegraph-mcp fails with a clear message rather than falling back if nothing is there.

Usage

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph-mcp",
      "args": []
    }
  }
}

Cursor / Windsurf / Cline / Other MCP clients

Same config — the codegraph-mcp command starts the server in MCP (stdio) mode.

Options

Pass flags after --:

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph-mcp",
      "args": ["--workspace", "/path/to/project", "--exclude", "vendor"]
    }
  }
}

Leave the transport out of args: codegraph-mcp already puts the engine in MCP (stdio) mode, so --mcp, --stdio and --connect are dropped from whatever the client passes rather than forwarded twice.

| Flag | Default | Description | |------|---------|-------------| | --workspace <path> | current dir | Directories to index (repeatable) | | --exclude <dir> | — | Directories to skip (repeatable) | | --embedding-model <model> | bge-small | bge-small, jina-code-v2, granite-97m (32K, multilingual), or static (model2vec, ~100× faster indexing, ~90% of BGE quality; needs a local model dir - this install downloads one to ~/.codegraph/static_models/jina-code-static-256, or point CODEGRAPH_STATIC_MODEL elsewhere) | | --max-files <n> | 5000 | Maximum files to index | | --profile <name> | all | Scope tool surface: core (8), graph (17), memory (14), security (pro), all (42) | | --graph-only | off | Skip embeddings — graph + structural tools only. No ONNX model load, 10-50× faster indexing. For CI / one-shot graph queries. | | --run-tool <name> | — | One-shot: index, run a single tool, print result, exit. No MCP handshake. Pair with --tool-args '<json>'. |

Troubleshooting: embeddings disabled / "Memory manager not initialized"

Before loading the ONNX embedding model, the server checks available memory and runs graph-only if under ~1.5 GB, so an OOM-kill can't take down the process. If that check misfires, index_markdown, search_docs, memory_*, and semantic search are unavailable while graph-only tools keep working.

• A reading of 0 MB available is treated as a detection failure and the model loads anyway. On macOS, reclaimable memory is parked in inactive/speculative/purgeable pages that some memory readers don't count as free, so a healthy Mac can report 0.
• If embeddings stay disabled even though the machine has plenty of free RAM, set CODEGRAPH_SKIP_MEMORY_CHECK=1 (also accepts true/yes) to bypass the check entirely.

Both apply in MCP mode and one-shot --run-tool mode.

Agent rules (recommended)

Pre-configured rule files that teach your AI agent to use CodeGraph tools before falling back to grep / multi-file reads:

→ codegraph-rules-for-agents

GitHub Action — automatic PR review

Get a code-graph analysis comment on every PR — blast radius, test gaps, stale docs, suggested reviewers. Runs graph-only (no embeddings, no API keys, just GITHUB_TOKEN). The core invocation:

codegraph-server --graph-only \
  --run-tool codegraph_pr_context \
  --tool-args '{"baseBranch":"main","format":"markdown"}'

This prints a ready-to-post markdown PR comment. A copy-paste workflow template lives at .github/workflows/codegraph-pr.yml in the main repo.

Optional: automatic context injection in Claude Code

Install a PreToolUse hook that nudges Claude to fetch graph context (get_edit_context, analyze_impact) before editing source files in indexed workspaces. Skips non-source files and ad-hoc edits silently. Never blocks tool calls.

npx codegraph-mcp-install-hooks         # interactive prompt
npx codegraph-mcp-install-hooks --dry   # preview the change
npx codegraph-mcp-install-hooks --force # skip prompt
npx codegraph-mcp-install-hooks --uninstall

Tools (42)

Analysis (11): get_ai_context, get_edit_context, get_curated_context, analyze_impact, analyze_complexity, find_circular_deps, find_hot_paths, find_dead_imports, get_module_summary, search_by_pattern, search_by_error

PR review (1): pr_context — one-call PR analysis: blast radius, test gaps, stale docs, commit hint, suggested reviewers. Supports format:"markdown" for ready-to-post CI comments.

Navigation (13): symbol_search, get_callers, get_callees, get_detailed_symbol, get_symbol_info, get_dependency_graph, get_call_graph, find_by_imports, find_by_signature, find_entry_points, find_implementors, find_related_tests, traverse_graph

Memory (7): memory_store, memory_get, memory_search, memory_context, memory_list, memory_stats, memory_invalidate

Documentation (7): index_markdown, search_docs, list_doc_sources, remove_doc_source, verify_design, design_gaps, generate_architecture_doc

Indexing (3): reindex_workspace, index_files, index_directory

All tool names are prefixed with codegraph_ (e.g. codegraph_symbol_search).

Languages (38)

Systems: C, C++, Rust, Zig, Objective-C
JVM: Java, Kotlin, Scala, Groovy, Clojure
Web/Scripting: TypeScript/JS, Python, Ruby, PHP, Perl, Lua, Elixir, Elm
Web/Style: CSS
Mobile: Swift, Dart
Functional: Haskell, OCaml, Julia, Erlang
Enterprise: C#, COBOL, Fortran, Go
Blockchain: Solidity
Shell/Config: Bash, HCL/Terraform, TOML, YAML, Dockerfile
Hardware: Verilog/SystemVerilog, Tcl
Data Science: R

Telemetry

Anonymous usage telemetry helps improve CodeGraph. Events tracked: tool invocations (name + duration), startup, errors. No file paths, code content, or PII is ever sent.

Opt out: set CODEGRAPH_TELEMETRY=off in your environment.

License

Apache-2.0 — GitHub