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

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#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), 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). 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) 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:

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):

cgr daemon up

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

code-graph-rag mcp-server

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

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):

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):

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):

• 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).
• 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 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.

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