# How to Integrate Code-Graph-RAG with Claude Code: Complete MCP Server Guide

> Integrate Code-Graph-RAG with Claude Code to query, navigate, and edit codebases using natural language. This guide provides a complete MCP server setup for seamless integration.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-09-04

---

**The Code-Graph-RAG MCP server exposes the RAG engine as a remote tool via the Model Context Protocol, allowing Claude Code to query, navigate, and edit codebases through natural-language conversations.**

Code-Graph-RAG is an open-source retrieval-augmented generation system that indexes code into a Neo4j-compatible graph. By integrating it with Claude Code through the MCP (Model Context Protocol) interface, you can transform your AI assistant into a codebase expert that understands structure, dependencies, and semantics.

## MCP Architecture for Code-Graph-RAG

The integration relies on a dedicated MCP server implementation that bridges Claude Code with the graph database. In [[`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py#L44-L57), the `mcp_server` command serves as the entry point, dispatching to either STDIO or HTTP transports based on your configuration.

The server implementation resides in [[`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py), which handles JSON-RPC requests from Claude Code and routes them to the appropriate tool handlers defined in [[`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py). This architecture ensures that Claude Code communicates with your codebase through deterministic graph queries rather than relying solely on LLM context windows.

## Environment Configuration

Before starting the server, configure these required environment variables in your shell or Claude Code settings:

- **`TARGET_REPO_PATH`** – Absolute path to the codebase you want to index and query.
- **`CYPHER_PROVIDER`** – LLM provider for Cypher query generation (`openai`, `google`, or `ollama`).
- **`CYPHER_MODEL`** – Specific model identifier (e.g., `gpt-5.6-luna`, `gemini-3.5-flash-lite`).
- **`CYPHER_API_KEY`** – API key for the chosen provider.

These variables are read from [[`codebase_rag/constants/settings.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/settings.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/settings.py) at runtime. For HTTP transport, you may also specify `MCP_HTTP_HOST` and `MCP_HTTP_PORT` to override the default binding.

## Installing and Starting the Server

First, clone the repository and install dependencies:

```bash
git clone https://github.com/vitali87/code-graph-rag.git
cd code-graph-rag
uv sync  # or pip install -e .

```

Start the supporting infrastructure (Memgraph and Qdrant):

```bash
cgr daemon up

```

Launch the MCP server using STDIO transport (recommended for local Claude Code integration):

```bash
code-graph-rag mcp-server

```

For HTTP transport (useful for remote or containerized deployments):

```bash
code-graph-rag mcp-server --transport http --host 0.0.0.0 --port 8000

```

## Configuring Claude Code as an MCP Client

Add the Code-Graph-RAG server to Claude Code using the built-in MCP management commands.

**STDIO Transport (Local):**

```bash
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH="$(pwd)" \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-5.6-luna \
  --env CYPHER_API_KEY=$OPENAI_API_KEY \
  -- code-graph-rag mcp-server

```

**HTTP Transport (Remote):**

```bash
claude mcp add --transport http code-graph-rag \
  --env TARGET_REPO_PATH="/srv/myrepo" \
  --env CYPHER_PROVIDER=google \
  --env CYPHER_MODEL=gemini-3.5-flash-lite \
  --env CYPHER_API_KEY=$GOOGLE_API_KEY \
  --host 0.0.0.0 --port 8000 \
  -- code-graph-rag mcp-server

```

Once added, Claude Code will automatically discover the available tools and expose them during your conversations.

## Available RAG Tools

The MCP server exposes the following deterministic tools from [[`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py):

- **`list_projects`** – Displays all indexed repositories in the graph database.
- **`index_repository`** – Parses and ingests a new repository into the graph structure.
- **`update_repository`** – Incrementally updates the graph after code changes.
- **`resolve`** – Maps a name or location to qualified graph nodes.
- **`definition`** – Retrieves source code, file paths, and docstrings for specific definitions.
- **`callers`** and **`callees`** – Traverse the call graph to find function dependencies.
- **`semantic_search`** – Locates functions by natural-language description (requires the `semantic` extra).
- **`structural_search`** and **`structural_replace`** – AST-based pattern matching and refactoring (requires the `ast-grep` extra).
- **`ask_agent`** – Sends open-ended questions to the LLM-powered RAG agent.

Most tools execute fixed Cypher queries against the graph, ensuring fast, deterministic responses. The `ask_agent` tool invokes the LLM for complex reasoning tasks.

## Practical Usage Examples

After integration, interact with your codebase through natural language:

**Listing indexed projects:**

```

User: "What projects do you have indexed?"
Claude: [Calls `list_projects`] → "I found three projects: api-service, frontend-client, and shared-lib."

```

**Navigating code structure:**

```

User: "Show me the definition of auth.service.Login"
Claude: [Calls `definition` on the resolved qualified name] → "Here is the Login class in auth/service.py..."

```

**Analyzing dependencies:**

```

User: "Find all functions that call UserService.create_user"
Claude: [Calls `callers` with the qualified name] → "I found 4 callers: validate_user in validators.py, setup_demo in fixtures.py..."

```

**Semantic search:**

```

User: "Find functions that handle JWT token validation"
Claude: [Calls `semantic_search`] → "I found verify_token in auth/jwt.py and check_expiry in middleware/security.py..."

```

## Summary

- **Code-Graph-RAG** exposes its capabilities through an **MCP server** implemented in [[`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py).
- The integration requires setting **four environment variables** (`TARGET_REPO_PATH`, `CYPHER_PROVIDER`, `CYPHER_MODEL`, `CYPHER_API_KEY`) before starting the server.
- Use **`claude mcp add`** with either STDIO or HTTP transport to connect Claude Code to the running server.
- Once connected, Claude Code can execute **deterministic graph queries** to resolve definitions, traverse call hierarchies, and perform semantic searches without relying on file context limits.
- Refer to the [official MCP server documentation](https://github.com/vitali87/code-graph-rag/blob/main/docs/guide/mcp-server.md) for advanced configuration options.

## Frequently Asked Questions

### What transport protocol should I use for Claude Code integration?

Use **STDIO transport** for local development and single-machine setups, as it provides the lowest latency and simplest configuration. Use **HTTP transport** when running Code-Graph-RAG on a remote server, in a container, or when multiple clients need to share the same indexed graph instance.

### Which LLM providers are supported for Cypher query generation?

Code-Graph-RAG supports **OpenAI**, **Google Gemini**, and **Ollama** as Cypher providers. Set `CYPHER_PROVIDER` to `openai`, `google`, or `ollama` respectively, and ensure the corresponding `CYPHER_MODEL` and `CYPHER_API_KEY` values are configured in your environment.

### How do I update the graph when my code changes?

Use the **`update_repository`** tool through Claude Code after modifying your source files. This performs an incremental update rather than a full re-index, preserving existing graph relationships while adding new nodes and edges for changed code. For major refactoring, you may want to run `index_repository` again to rebuild the graph from scratch.

### Do I need to install Memgraph separately?

No, if you use the built-in orchestration commands. Running `cgr daemon up` automatically starts both **Memgraph** (for the code graph) and **Qdrant** (for semantic search) in Docker containers. Ensure Docker is installed and running on your system before executing this command.