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

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 wraps the core functionality. It instantiates MCPToolsRegistry (defined in 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 (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:

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

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

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:

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 (which defines MCPEnvVar constants) and initializes the tool registry via create_mcp_tools_registry exposed in codebase_rag/mcp/__init__.py.

Registering with Claude Code

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

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:

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:

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 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, including pagination limits and log format specifications.

Usage Examples

After registration, interact with your codebase using natural language:

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:

claude mcp remove code-graph-rag

Summary

• Code-Graph-RAG provides an MCP server in 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.
• Key tools include query_code_graph, structural_search, and ask_agent, all registered through MCPToolsRegistry in 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) 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}