Code Graph MCP

Stop your coding agent from grepping. Give it a graph of the codebase instead.

Semantic code search, call graphs, control and data flow, impact analysis. Served to AI coding agents over MCP.

Overview

Code Graph turns a repository into a queryable graph: every file, symbol, call, import, control-flow branch and variable, indexed with semantic embeddings and served to AI coding agents through the Model Context Protocol.

Instead of guessing keywords and reading whole files, an agent asks structural questions and gets structural answers, with the real source attached.

Related MCP server: codebase-rag

Search your codebase in the browser

The web app at http://localhost:8989 is for you, not your agent. Search the codebase by intent, expand what comes back, and follow the calls and imports across the canvas. The graph it draws is the one the server built, so it is also a quick way to check the index is healthy before you rely on it.

Everything runs locally. Parsing, embedding and storage happen in containers on your machine. No code leaves it.

Quick start

Prerequisites: Docker Engine 24+ with Compose v2, or Docker Desktop. Nothing else. Go and Node are only needed for native development.

git clone https://github.com/attaxr/code-graph-mcp.git
cd code-graph-mcp/deploy

./deploy.sh up          # Windows PowerShell: .\deploy.ps1 up
./deploy.sh index       # one-shot index of the mounted repo

Open http://localhost:8989. The MCP endpoint is http://localhost:8989/mcp.

Two things to expect on the first run:

• The first start is slow. The embedding container downloads its model before it can serve requests, which takes about two minutes. Every start after that is quick, and re-indexing is incremental.

• The graph holds one repository at a time. It is keyed by repo-relative paths, so pointing it at a new project clears the previous one instead of merging two codebases.

Point it at your own project

Install the codegraph CLI and run one command from inside the project you want indexed. No compose edits, no restart:

cd /path/to/your/project
codegraph init

Your agent can do the same thing mid-conversation by calling initialize_project.

To set the target permanently instead, name it in deploy/.env:

echo "TARGET_REPO=/absolute/path/to/your/project" >> deploy/.env
./deploy.sh up          # `up`, not `restart`: restart reuses containers
./deploy.sh index

The codegraph CLI

codegraph is a terminal front-end for the server. It points the server at a repository, builds the graph, keeps it in sync, and reports on it, from any directory, without editing docker-compose or reaching for curl.

Install

go install github.com/attaxr/code-graph-mcp/apps/code-graph-cli/cmd/codegraph@latest

That drops codegraph in $GOBIN (usually ~/go/bin, or %USERPROFILE%\go\bin on Windows). Make sure it is on your PATH.

No Go toolchain? Every release ships prebuilt archives for Linux, macOS and Windows on amd64 and arm64. Unpack one and put codegraph on your PATH.

Usage

Index a codebase. Run this from inside the project you want indexed. It resolves the git checkout root, switches the server to that repository, and follows the index run to completion:

cd /path/to/your/project
codegraph init

Keep the graph in sync after edits. Only changed files are re-parsed and re-embedded, so this takes seconds:

codegraph sync

Rebuild from scratch after large moves, renames, or an embedding model change:

codegraph rebuild

Check what the server is pointed at, whether a run is in flight, and what the graph holds:

codegraph status

Index a different project without leaving this one, and do it in the background:

codegraph init ../other-project --no-wait

Work against a remote or token-protected server:

codegraph --server https://codegraph.example.com --token <token> status
codegraph login          # verify the token once and store it

When something is wrong, diagnose checks reachability, auth, the health endpoint, index status and graph stats, printing a pass or fail line for each:

codegraph diagnose

Prefer a menu? codegraph tui runs the same operations interactively.

Commands

config on its own prints the effective configuration. Four subcommands manage the file, and the only keys are server and token:

Flags

Every flag is global, so it can be passed to any command.

Configuration and tokens

Settings are resolved in this order, with the first match winning:

1. Flags: --server, --token

2. Environment: CODE_GRAPH_URL, then CODE_GRAPH_TOKEN, then API_TOKEN

3. Config file: ~/.config/code-graph/config.json on Linux and macOS, %AppData%\code-graph\config.json on Windows. Written by codegraph login and codegraph config set, with user-only permissions

4. Default: http://localhost:8989, no token

If no token is found in any of those, the CLI looks inside the current repository, first at deploy/.env for API_TOKEN=, then at .mcp.json for an Authorization: Bearer header. That means a checkout that already talks to a protected server needs no extra setup.

Migrating from the init scripts

codegraph replaces the old scripts/code-graph-init.sh and scripts/code-graph-init.ps1 (now removed). The mapping is direct:

Environment variables are unchanged: CODE_GRAPH_URL, CODE_GRAPH_TOKEN and API_TOKEN all still work, as does the automatic token discovery from deploy/.env and .mcp.json. Anything that piped the scripts through irm | iex or curl | sh becomes one go install plus codegraph init.

Indexing without the CLI

deploy.sh still drives a one-shot index inside the running container:

cd deploy
./deploy.sh index           # Windows PowerShell: .\deploy.ps1 index
./deploy.sh index -force    # re-embed everything

Either way, the repository named in TARGET_REPO (deploy/.env, default .., your repo root) is mounted read-only at /workspace, so your source is never modified. The graph lives in Neo4j. To verify a run finished, use codegraph status, poll curl -s http://localhost:8989/api/stats until files and symbols are non-zero, or open http://localhost:8989.

Connect your AI agent

Two steps: register the server, then install the skills that teach your agent when to use it.

1. Register the MCP server

The endpoint is always http://localhost:8989/mcp, the transport is streamable HTTP, and the server name is code-graph. Everything below is those three values in a different file.

Most of them take this shape:

{
  "mcpServers": {
    "code-graph": {
      "type": "http",
      "url": "http://localhost:8989/mcp"
    }
  }
}

Zed and OpenCode nest it under mcp instead, and OpenCode calls the transport remote:

{
  "mcp": {
    "code-graph": {
      "type": "remote",
      "url": "http://localhost:8989/mcp",
      "enabled": true
    }
  }
}

Zed applies the change live. Restart it only if the tools do not appear.

VS Code can register the server from the command line instead of a file:

code --add-mcp '{
  "name": "code-graph",
  "type": "http",
  "url": "http://localhost:8989/mcp"
}'

This repo also ships a root .mcp.json, which Claude Code, VS Code and Copilot read automatically for project-level MCP servers.

2. Install the skills

The skills teach your agent which tool answers which question, and to stop reaching for grep. One command works on every agent:

cd /path/to/your/project
npx skills add attaxr/code-graph-mcp --all -y

To target a single agent, pass -a <agent>:

npx skills add attaxr/code-graph-mcp -a claude-code -g -y

The bundle contains eight skills: code-graph (the router), plus code-graph-onboarding, code-graph-references, code-graph-tracing, code-graph-impact, code-graph-reuse, code-graph-cypher and code-graph-indexing.

Claude Code can install them as a plugin instead:

claude plugin marketplace add attaxr/code-graph-mcp
claude plugin install code-graph@code-graph

Gemini CLI takes them as an extension:

gemini extensions install https://github.com/attaxr/code-graph-mcp

For any other agent, copy the skills/*/SKILL.md playbooks from this repo into its skills or rules directory.

Or let the agent set it up

Paste this into any MCP-capable coding agent. It does the whole setup and verifies it.

Set up the Code Graph MCP Server for this project and use it instead of grep from now on.

1. START
   Clone https://github.com/attaxr/code-graph-mcp to ../code-graph-mcp (git pull if it already
   exists). In its deploy/ dir, set TARGET_REPO in .env to MY project's absolute path, then run
   `./deploy.sh up` (PowerShell: `.\deploy.ps1 up`) and `./deploy.sh index`. The first run
   downloads an embedding model, so allow a few minutes. Poll
   `curl -s http://localhost:8989/api/stats` until files and symbols are non-zero.

2. SKILLS
   Run `npx skills add attaxr/code-graph-mcp --all -y` in MY project. If that CLI is unavailable,
   install the skills from the clone's skills/ directory into whatever mechanism you support.

3. CONNECT
   Register a server named `code-graph` at http://localhost:8989/mcp (streamable HTTP) using your
   usual MCP configuration. If you don't know your config format, print the exact JSON for me to
   paste instead of writing to a guessed path.

4. VERIFY: show me the real output, not a summary
   a) confirm the code-graph tools are connected (reload/restart first if needed)
   b) index_status()
   c) explain_feature("<the main thing this project does>")

5. REPORT
   Tell me: clone path, index stats, what you configured where, and anything that failed.
   From now on, use the code-graph tools instead of grep/ripgrep/find to locate code, trace
   relationships or understand an implementation, and run search_code before writing any new
   function. Keep text search for non-code text only.

If the stack is already running, paste steps 2 to 5 alone.

Running the stack

The whole stack (Neo4j, the embedding server, the Go MCP/HTTP backend and the web app) is defined in deploy/docker-compose.yml. Two scripts drive it with identical commands, one per platform:

• deploy/deploy.sh for Linux, macOS, WSL and Git Bash.

• deploy/deploy.ps1 for Windows PowerShell.

Run every command from the deploy/ directory, where .env and the compose file live. The first up copies deploy/.env.example to deploy/.env automatically.

cd deploy
./deploy.sh up              # build images and start the stack detached
./deploy.sh ps              # container state (alias: status)
./deploy.sh logs -f         # tail logs (`logs -f nginx` for one service)
./deploy.sh restart         # restart all services
./deploy.sh down            # stop and remove containers (`-v` drops volumes)

What up starts:

Only nginx publishes a port. The rest live on the internal compose network.

To update to the latest version:

git pull
./deploy.sh rebuild         # rebuild images and restart the stack
# or: ./deploy.sh pull && ./deploy.sh up     # pull images without rebuilding
# `rebuild --no-cache` forces a clean build

Named volumes (neo4j-data, neo4j-logs, hf-cache) survive down and restart. Only down -v deletes them.

Configuration

On first start, deploy.sh up copies deploy/.env.example to deploy/.env. Edit that file, then re-run ./deploy.sh up. Do not use restart: it does not recreate containers, so new values are not picked up.

Trailing-space warning. EMBED_QUERY_PREFIX and EMBED_DOCUMENT_PREFIX end in a space, which the compose .env parser trims from unquoted values. If you enable them, keep them quoted exactly as in .env.example.

Authentication

Auth is opt-in. Leave API_TOKEN empty (the default) for a trust-your-localhost setup. Set it to require a token on every /api/* and /mcp request.

echo "API_TOKEN=<a-long-random-token>" >> deploy/.env
cd deploy && ./deploy.sh up     # recreate containers so they pick it up

How it works:

• Compose delivers the token to the mcp-server and nginx containers at runtime via env_file. It is never baked into an image.

• The server guards the whole HTTP surface. Every request must present the token as Authorization: Bearer <token> or X-API-Key: <token>. Anything else gets a 401 with WWW-Authenticate: Bearer realm="code-graph". Tokens are compared in constant time, so a wrong token cannot be told from a correct one by timing.

• The web UI keeps working with auth on. The nginx entrypoint writes the token into /config.js at container start, and the SPA sends it automatically.

• After changing the token, re-run ./deploy.sh up. restart will not pick it up.

Check that both surfaces are guarded:

# REST API: 401 without the token, 200 with it
curl -i http://localhost:8989/api/health
curl -i \
  -H "Authorization: Bearer <token>" \
  http://localhost:8989/api/health

# MCP endpoint: same 401, same 200 once the header is added
curl -i -X POST http://localhost:8989/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "0" }
    }
  }'

The CLI takes the token as a flag, or finds it itself in deploy/.env or .mcp.json when you run inside the checkout:

codegraph --token <token> status
codegraph login             # verify once and store it for later commands

Sending the token from an MCP client

Every client config in Connect your AI agent accepts a headers field:

// VS Code / Cursor: .mcp.json
{
  "mcpServers": {
    "code-graph": {
      "type": "http",
      "url": "http://localhost:8989/mcp",
      "headers": { "Authorization": "Bearer <token>" },
    },
  },
}

// Zed: settings.json
{
  "mcp": {
    "code-graph": {
      "url": "http://localhost:8989/mcp",
      "headers": { "Authorization": "Bearer <token>" },
    },
  },
}

For OpenCode, add the same headers entry to opencode.json under mcp.code-graph. Plugin-based clients such as Claude Code and Gemini CLI take the token in their MCP server settings. It is the same Authorization: Bearer <token> header on the same URL.

How it works

./deploy.sh up starts four services behind a single nginx entry point at http://localhost:8989:

nginx (:8989) ── /        static web app
              ├── /api/*  ──> mcp-server :7788
              └── /mcp    ──> mcp-server :7788   (streamable MCP)

mcp-server ──> neo4j      graph store + vector indexes
mcp-server ──> embeddings local embedding model

An index pass parses every file with tree-sitter, resolves symbols and edges, and stores them in Neo4j with semantic embeddings. Your agent's MCP tools (explain_feature, find_callers and the rest) query that graph and get the real source back. The web app reads the same graph over /api/*, which is how you search and explore it yourself.

Bug reports

Found a bug? Open a new issue and include:

• What you did. Steps to reproduce.

• What you expected, and what happened instead.

• Index stats if relevant: curl -s http://localhost:8989/api/stats, or the output of index_status().

• Container logs if the stack is involved: ./deploy.sh logs.

Contributing

Contributions are welcome: code, docs, skills and issues all count.

• Set up for development. ./deploy.sh --dev up runs the stack with Vite HMR. The Go server lives in services/mcp-server/, the web app in apps/web/.

• Graph schema. The single source of truth is services/mcp-server/internal/graph/schema.go. The TypeScript mirror in packages/graph-schema/src/generated.ts is generated from it, so edit the Go file and run go generate ./internal/graph. Never edit the generated file.

• Open a pull request from a fork with a clear description of what and why. Tests and a re-index of your change (./deploy.sh index) are appreciated.

Contributors

License

Released under the MIT License. Copyright 2026 Code Graph MCP contributors.

MIT is a permissive open-source license: you may use, copy, modify, merge, publish, distribute, sublicense and sell the software, provided the copyright notice and permission text are included in all copies or substantial portions. The software is provided as is, without warranty of any kind.

See LICENSE for the full text.