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

> Integrate Code-Graph-RAG with Claude Code MCP by registering cgr mcp-server using stdio, setting env vars, and running Memgraph for natural language codebase queries. Get the complete setup guide now.

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

---

**You can integrate Code-Graph-RAG with Claude Code by registering the `cgr mcp-server` command as a Model Context Protocol (MCP) server using stdio transport, configuring the required environment variables, and ensuring the Memgraph backend is running to enable natural language codebase queries.**

Code-Graph-RAG transforms your repository into a queryable knowledge graph stored in Memgraph, enabling semantic code search via Cypher queries generated by LLMs. When you integrate Code-Graph-RAG with Claude Code MCP, Claude gains the ability to navigate, analyze, and answer questions about your codebase through structured graph queries rather than simple text search, all without requiring direct filesystem access to your repository.

## Prerequisites for MCP Integration

Before connecting Code-Graph-RAG to Claude Code, ensure your environment meets these requirements:

- **Running Memgraph Instance**: The knowledge graph backend must be active. Start it with `cgr daemon up`, which initializes both Memgraph and Qdrant vector storage.
- **Python Environment**: Code-Graph-RAG must be installed (`pip install code-graph-rag`) or available via `uv run` for source installations.
- **Claude Code CLI**: You need the Claude Code command-line tool installed to register MCP servers.
- **API Credentials**: Valid API keys for your chosen Cypher generation provider (OpenAI, Anthropic, etc.) set via environment variables.

## Architecture Overview

The integration operates through three distinct layers that separate concerns between storage, reasoning, and transport:

1. **Knowledge Graph Layer**: Memgraph stores the parsed Abstract Syntax Tree (AST) of your codebase as nodes and relationships, enabling complex graph traversals.
2. **MCP Server Layer**: The `mcp_server` function 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#L900-L920) (lines 900-920) exposes deterministic tools like `semantic_search`, `index_repository`, and `ask_agent` via stdio transport.
3. **Client Interface Layer**: Claude Code spawns the MCP server as a subprocess and routes natural language queries through the [`query_mcp_server`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16) function in [[`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16) (lines 8-16), which dispatches requests to the appropriate graph operations.

## Step-by-Step Integration Guide

### Start the Knowledge Graph Backend

First, initialize the infrastructure that stores your codebase graph:

```bash

# Start Memgraph and Qdrant containers

cgr daemon up

```

Keep this running in a separate terminal or background process, as the MCP server requires an active graph database connection to answer queries.

### Register the MCP Server with Claude Code

Use the Claude Code CLI to add Code-Graph-RAG as an MCP server. The registration command specifies stdio transport and passes the necessary environment variables:

```bash
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH="/absolute/path/to/your/repo" \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-5.6-luna \
  --env CYPHER_API_KEY=sk-your-api-key-here \
  -- code-graph-rag mcp-server

```

The `--env` flags inject configuration directly into the MCP server process. **Critical**: Use absolute paths for `TARGET_REPO_PATH` to ensure the server can locate your repository regardless of invocation context.

### Configure Environment Variables

The MCP server reads these specific environment variables during initialization:

- **`TARGET_REPO_PATH`**: Absolute filesystem path to the repository you want to query. The server indexes and monitors this directory.
- **`CYPHER_PROVIDER`**: LLM provider for generating graph queries (e.g., `openai`, `anthropic`, `ollama`).
- **`CYPHER_MODEL`**: Specific model name for Cypher generation (e.g., `gpt-4`, `claude-3-opus`).
- **`CYPHER_API_KEY`**: Authentication token for the specified provider.

For local development with source installations, substitute `code-graph-rag` with `uv run cgr mcp-server` in the registration command.

## Using the Integration

Once registered, Claude Code can invoke Code-Graph-RAG tools through natural language. Common workflows include:

**Index a repository**:

```bash
> index_repository

```

This triggers the graph construction process, parsing all supported files in `TARGET_REPO_PATH` into the Memgraph instance.

**Semantic code search**:

```bash
> semantic_search "functions that handle authentication"

```

**Graph-based navigation**:

```bash
> What classes inherit from BaseRepository?
> Find all callers of UserService.create_user

```

**Direct Python API access**:

If building custom automation, use the client library directly:

```python
from codebase_rag.mcp.client import query_mcp_server

response = query_mcp_server("List all middleware classes in the API module")
print(response["answer"])

```

The `query_mcp_server` function in [[`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16) handles JSON serialization and stdio communication with the running MCP server process.

## Key Implementation Files

Understanding these source files helps with debugging and customization:

- **[[`docs/guide/mcp-server.md`](https://github.com/vitali87/code-graph-rag/blob/main/docs/guide/mcp-server.md)](https://github.com/vitali87/code-graph-rag/blob/main/docs/guide/mcp-server.md)**: Comprehensive documentation covering advanced configuration, troubleshooting, and tool descriptions.
- **[[`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#L900-L920)** (lines 900-920): Contains the `mcp_server` entry point that parses arguments and initializes the server process.
- **[[`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16)** (lines 8-16): Implements `query_mcp_server`, the stdio communication layer that formats requests and parses JSON responses for MCP clients.
- **[[`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)**: Defines the deterministic tool implementations (e.g., `resolve`, `definition`, `ask_agent`) exposed through the MCP interface.

## Summary

- **Transport Protocol**: Code-Graph-RAG integrates with Claude Code exclusively via **stdio transport**, making it compatible with the `claude mcp add` command.
- **Environment Configuration**: Four critical variables (`TARGET_REPO_PATH`, `CYPHER_PROVIDER`, `CYPHER_MODEL`, `CYPHER_API_KEY`) must be set during registration to authenticate with LLM providers and locate the target codebase.
- **Backend Dependency**: The Memgraph database must be running (`cgr daemon up`) before starting the MCP server, as all operations query the knowledge graph stored there.
- **Architecture**: The [`query_mcp_server`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16) function acts as the bridge between Claude Code's natural language interface and the deterministic graph tools implemented in the codebase.

## Frequently Asked Questions

### What environment variables are required to connect Code-Graph-RAG with Claude Code?

You must provide `TARGET_REPO_PATH` (absolute path to your repository), `CYPHER_PROVIDER` (LLM service name), `CYPHER_MODEL` (specific model identifier), and `CYPHER_API_KEY` (authentication token). These are passed via `--env` flags when running `claude mcp add` to ensure the MCP server can authenticate with your LLM provider and locate the codebase.

### Can I use a local LLM instead of OpenAI for Cypher generation?

Yes. Set `CYPHER_PROVIDER` to `ollama` or another local-compatible provider, and specify your local model name in `CYPHER_MODEL`. Ensure the local inference server is accessible from the environment where `cgr mcp-server` runs, and provide any necessary local API keys or endpoints through the environment variable configuration.

### How do I index a new repository after setting up the MCP server?

Use the `index_repository` tool directly within Claude Code after the integration is active. Alternatively, run `cgr index /path/to/repo` from your terminal before starting the MCP server. The server references the pre-built graph in Memgraph, so indexing must occur against the same `TARGET_REPO_PATH` specified in your MCP configuration.

### Why does the MCP server require stdio transport specifically?

Claude Code's MCP client architecture spawns servers as subprocesses and communicates via standard input/output streams. The [`query_mcp_server`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py#L8-L16) implementation in Code-Graph-RAG is designed to read JSON-RPC messages from stdin and write responses to stdout, ensuring compatibility with Claude's sandboxed process model without requiring network ports or HTTP servers.