# How to integrate Code-Graph-RAG with Claude Code via MCP server

> Integrate Code-Graph-RAG with Claude Code using the MCP server. Query your codebase structure and semantics with natural language. Learn how with this guide.

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

---

**Code-Graph-RAG exposes its knowledge graph and RAG pipeline through an MCP server that Claude Code can connect to, enabling natural language queries against your codebase structure and semantics.**

The vitali87/code-graph-rag repository provides a native **MCP (Model Context Protocol)** integration that turns Claude Code into an intelligent interface for exploring codebases. By connecting Claude to the Code-Graph-RAG MCP server, you can query semantic relationships, structural dependencies, and symbol definitions using conversational prompts rather than manual Cypher queries or shell commands.

## Architecture Overview

The integration relies on three components working over a standardized RPC interface.

### The Code-Graph-RAG Core

At the foundation, the system parses repositories using Tree-sitter to build a language-agnostic knowledge graph stored in **Memgraph**. A RAG pipeline translates natural language queries into Cypher or invokes specialized analysis tools. This core layer handles the heavy lifting of code comprehension and vector search via Qdrant.

### The MCP Server Implementation

The server implementation in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) wraps the core functionality. It instantiates `MCPToolsRegistry` (defined in [`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py)) and registers all available tools—such as `list_projects`, `query_code_graph`, `ask_agent`, and `structural_search`—with an `mcp.Server` instance. The server listens on **stdio** by default, though HTTP transport is also supported.

### Claude Code as MCP Client

Claude Code acts as the MCP client using the `claude mcp` CLI. When you register the Code-Graph-RAG server, Claude loads the tool schemas from [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py) (which defines tool identifiers like `MCPToolName.ASK_AGENT`). User prompts are forwarded to the server, which returns structured JSON results that Claude renders as readable answers.

## Prerequisites and Installation

Before connecting to Claude Code, you must install the Code-Graph-RAG CLI and start its backing services.

Install the tool with all language parsers:

```bash
uv tool install "code-graph-rag[treesitter-full,semantic]"

```

Start the background services (Memgraph and Qdrant) via Docker:

```bash
cgr daemon up

```

## Setting Up the MCP Server

You can run the server using either stdio (recommended for CLI integration) or HTTP transport.

### Starting the Server

Launch the MCP server on stdio by specifying the target repository through environment variables:

```bash
export TARGET_REPO_PATH=/absolute/path/to/project
export CYPHER_PROVIDER=openai
export CYPHER_MODEL=gpt-5.6-luna
export CYPHER_API_KEY=$OPENAI_API_KEY

code-graph-rag mcp-server

```

The server reads configuration defaults from [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) (which defines `MCPEnvVar` constants) and initializes the tool registry via `create_mcp_tools_registry` exposed in [`codebase_rag/mcp/__init__.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/__init__.py).

### Registering with Claude Code

Add the running server to Claude’s MCP client list using the stdio transport:

```bash
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/absolute/path/to/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-5.6-luna \
  --env CYPHER_API_KEY=$OPENAI_API_KEY \
  -- code-graph-rag mcp-server

```

Verify the registration succeeded:

```bash
claude mcp list

```

This command displays the `code-graph-rag` entry along with all tools loaded from `MCPToolsRegistry`.

### HTTP Transport Configuration

For scenarios requiring network-based connectivity, start the server with HTTP support and register it using the HTTP transport:

```bash
claude mcp add --transport http code-graph-rag-http \
  --env TARGET_REPO_PATH=/abs/path \
  --env CYPHER_PROVIDER=google \
  --env CYPHER_MODEL=gemini-3.5-flash-lite \
  --env CYPHER_API_KEY=$GOOGLE_API_KEY \
  -- http://127.0.0.1:8000/mcp

```

The [`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py) module provides helper utilities that the CLI uses to manage these HTTP sessions and parse returned JSON.

## Available Tools and Operations

Once connected, Claude Code can invoke any tool registered in `MCPToolsRegistry`. The primary operations include:

- **`list_projects`** – Enumerates indexed repositories and their metadata.
- **`query_code_graph`** – Executes Cypher queries generated from natural language questions against the Memgraph backend.
- **`structural_search`** – Performs AST-based searches using Tree-sitter patterns.
- **`ask_agent`** – Routes complex, multi-step questions through the RAG pipeline for synthesized answers.

These tools leverage the configuration constants defined in [`codebase_rag/constants.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants.py), including pagination limits and log format specifications.

## Usage Examples

After registration, interact with your codebase using natural language:

```bash
claude ask "What functions call UserService.create_user?"

```

Claude forwards this prompt to the MCP server, which invokes `query_code_graph`, retrieves the call graph from Memgraph, and returns the results.

To remove the integration when finished:

```bash
claude mcp remove code-graph-rag

```

## Summary

- **Code-Graph-RAG** provides an MCP server in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) that exposes graph querying tools through a standardized protocol.
- **Claude Code** connects via `claude mcp add` using either stdio or HTTP transport, reading configuration from environment variables defined in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py).
- **Key tools** include `query_code_graph`, `structural_search`, and `ask_agent`, all registered through `MCPToolsRegistry` in [`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py).
- **Prerequisites** require running `cgr daemon up` to start Memgraph and Qdrant before launching the MCP server.
- **Integration** enables natural language exploration of codebases without writing manual Cypher queries.

## Frequently Asked Questions

### What transport protocols does the Code-Graph-RAG MCP server support?

The server supports both **stdio** (standard input/output) and **HTTP** transports. The stdio mode is the default and recommended for local CLI integration with Claude Code, while HTTP mode (configured via `serve_http` in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py)) enables network-based connections for remote setups.

### Which environment variables are required to configure the MCP server?

The server requires `TARGET_REPO_PATH` to specify the repository root to analyze. For Cypher generation capabilities, you must set `CYPHER_PROVIDER`, `CYPHER_MODEL`, and `CYPHER_API_KEY`. These variable names are defined as constants in [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) under the `MCPEnvVar` configuration class.

### How does Claude Code authenticate with the Code-Graph-RAG MCP server?

Authentication occurs through environment variables passed during the `claude mcp add` registration step. Claude spawns the server process with these variables injected into its environment, allowing [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) to access API keys and paths without additional handshake protocols.

### Can I use the MCP server with multiple repositories simultaneously?

The server instance is tied to a single `TARGET_REPO_PATH` at startup. To query multiple repositories, you must register separate MCP instances with unique names (e.g., `code-graph-rag-project-a` and `code-graph-rag-project-b`), each pointing to different paths. The `list_projects` tool can enumerate subgraphs if your single Memgraph instance contains multiple indexed repositories.