Repo Graphrag MCP

🚀 Repo GraphRAG MCP Server

Repo GraphRAG MCP Server is an MCP (Model Context Protocol) server. It uses LightRAG and Tree - sitter to construct a knowledge graph from code and text - based documents (text - only; PDFs/Word/Excel are not parsed) in a repository or directory. Then, it utilizes this graph for Q&A and implementation planning.

It offers tools for graph building (graph_create), implementation planning (graph_plan), and Q&A (graph_query).

• 📊 Knowledge graph creation (graph_create): Analyze code and documents to build a knowledge graph and embedding index, which supports incremental updates.
• 🔧 Implementation planning (graph_plan): Based on the knowledge graph (optionally combined with vector search), output implementation plans and specific change steps for modification or addition requests.
• 🔍 Q&A (graph_query): Answer questions about the target repository or directory based on the knowledge graph (optionally combined with vector search).

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv package manager
• Credentials for your chosen LLM provider. You need to set the required environment variables. Refer to the LLM Providers section below.

1. Installation

# Clone from GitHub
git clone https://github.com/yumeiriowl/repo-graphrag-mcp.git
cd repo-graphrag-mcp

# Install dependencies
uv sync

2. Environment Setup

# Copy the settings file
cp .env.example .env

# Edit the settings file
nano .env  # or any editor

3. Environment Variables (LLM Setup)

Configure settings in the .env file:

Example: Using Anthropic models

# LLM provider for graph creation
GRAPH_CREATE_PROVIDER=anthropic  # or openai, gemini, azure_openai

# Provider for planning and Q&A
GRAPH_ANALYSIS_PROVIDER=anthropic # or openai, gemini, azure_openai

# API keys (set the variables corresponding to your chosen provider)
ANTHROPIC_API_KEY=your_anthropic_api_key # or openai, gemini, azure_openai

# AZURE_OPENAI_API_KEY=your_azure_openai_api_key
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# AZURE_API_VERSION=azure_openai_api_version

# OPENAI_API_KEY=your_openai_api_key
# OPENAI_BASE_URL=http://localhost:1234/v1  # For LM Studio or other OpenAI-compatible local servers

# GEMINI_API_KEY=your_gemini_api_key

# LLM model for graph creation
GRAPH_CREATE_MODEL_NAME=claude-3-5-haiku-20241022

# LLM model for planning and Q&A
GRAPH_ANALYSIS_MODEL_NAME=claude-sonnet-4-20250514

4. MCP Client Setup

Claude Code

claude mcp add repo-graphrag \
-- uv --directory /absolute/path/to/repo-graphrag-mcp run server.py

VS Code GitHub Copilot Extensions

mcp.json:

{
  "servers": {
    "repo-graphrag-server": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/repo-graphrag-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Other MCP Clients

Any client that supports the MCP protocol can be used.

5. Usage

The following tools are available in MCP clients. All commands must start with graph:.

graph_create - Build/Update Knowledge Graph

Analyze the target repository/directory and build a knowledge graph and vector embedding index, which supports incremental updates. It uses GRAPH_CREATE_PROVIDER and GRAPH_CREATE_MODEL_NAME.

Elements:

• graph: (required)
• Directory path to analyze (absolute path recommended)
• Storage name to create (default: "storage")

Examples:

graph: /absolute/path/to/your/repository my_project
graph: /absolute/path/to/your/repository my_project graphify
graph: C:\\projects\\myapp webapp_storage please create storage

About Incremental Updates: When you run graph_create again with an existing storage name, only changed, added, or deleted files are re - analyzed; others are skipped. If you want to rebuild after changing the embedding model or extraction settings (DOC_DEFINITION_LIST, NO_PROCESS_LIST, target extensions, etc.), delete the existing storage or specify a new storage name and recreate with graph_create or standalone_graph_creator.py.

Note (Performance): The first graph creation takes longer as the number of files increases. As a guideline, if there are more than 1,000 files, consider narrowing the target directory. The processing time depends on the environment and file sizes. Incremental updates only re - analyze the diffs, so the above guideline does not necessarily apply to updates.

Note (First download): If the specified embedding model is not cached on the first graph creation, it will be automatically downloaded. Subsequent runs use the cache.

graph_plan - Implementation Support

Based on the knowledge graph (optionally combined with vector search), provide a detailed implementation plan and instructions so that the MCP client (agent) can perform actual work. It uses GRAPH_ANALYSIS_PROVIDER and GRAPH_ANALYSIS_MODEL_NAME.

Elements:

• graph: (required)
• Implementation/modification request
• Storage name (default: "storage")

Examples:

graph: I want to add user authentication my_project
graph: my_project Add GraphQL support to the REST API
graph: Improve API performance under high load webapp_storage

graph_query - Q&A

Based on the knowledge graph (optionally combined with vector search), answer questions about the target repository/directory. It uses GRAPH_ANALYSIS_PROVIDER and GRAPH_ANALYSIS_MODEL_NAME.

Elements:

• graph: (required)
• Question content
• Storage name (default: "storage")

Examples:

graph: Tell me about this project's API endpoints my_project
graph: my_project Explain the main classes and their roles
graph: About the database design webapp_storage

✨ Features

• Build a knowledge graph from code and text - based documents in a repository/directory.
• Provide tools for knowledge graph creation, implementation planning, and Q&A.
• Support incremental updates of the knowledge graph.
• Optionally combine vector search for implementation planning and Q&A.

📦 Installation

# Clone from GitHub
git clone https://github.com/yumeiriowl/repo-graphrag-mcp.git
cd repo-graphrag-mcp

# Install dependencies
uv sync

💻 Usage Examples

Basic Usage

# Create a knowledge graph
graph: /absolute/path/to/your/repository my_project

# Plan an implementation
graph: I want to add user authentication my_project

# Query information
graph: Tell me about this project's API endpoints my_project

📚 Documentation

⚙️ Configuration Options

LLM Providers

Specify the identifiers in .env as GRAPH_CREATE_PROVIDER / GRAPH_ANALYSIS_PROVIDER.

Embedding Model

• Default: BAAI/bge-m3
• Compatibility: Supports Hugging Face sentence - transformers compatible models
• First run: If the specified embedding model is not cached, it will be downloaded automatically. The cache location depends on the environment and settings. The download time and disk space depend on the model size.
• Authenticated models: For Hugging Face models that require authentication, set HUGGINGFACE_HUB_TOKEN in .env.

HUGGINGFACE_HUB_TOKEN=your_hf_token

Planning/Query Settings for graph_plan and graph_query

Implementation note: The settings in this section are passed directly to LightRAG's built - in QueryParam. This MCP does not implement custom retrieval or token - budgeting logic; it reuses LightRAG's behavior as is.

Retrieval/Search Modes

Search modes follow LightRAG. Set one of the following in .env SEARCH_MODE.

• mix: Combination of vector search and knowledge graph search (recommended)
• hybrid: Combination of local and global search
• naive: Simple vector search
• local: Community - based search
• global: Global community search

Token Budgets (Input - side)

Input - side token budgets control how much context is assembled for planning and Q&A (LightRAG QueryParam). These are independent from model output token limits.

• MAX_TOTAL_TOKENS: Overall input context budget per query (entities + relations + retrieved chunks + system prompt). Default: 30000.
• MAX_ENTITY_TOKENS: Budget for entity context (input - side). Default: 6000.
• MAX_RELATION_TOKENS: Budget for relation context (input - side). Default: 8000.

Note: Output token limits are controlled separately via GRAPH_ANALYSIS_MAX_TOKEN_SIZE (for planning/Q&A) and GRAPH_CREATE_MAX_TOKEN_SIZE (for graph creation tasks). If you increase input budgets significantly, ensure your model's total context window can accommodate both input and output.

Entity Merge

This MCP can merge entities extracted from documents with entities extracted from code based on semantic similarity. The goal is to unify references (e.g., a class or function defined in code and mentioned in documentation) into a single consolidated entity.

• How it works: Names are normalized and filtered via exclusion rules; document entities and current - pass code entities are embedded and compared using cosine similarity (FAISS). Pairs above the threshold are merged, consolidating descriptions and file paths.
• Controls:
  • MERGE_ENABLED (default: true): Toggle entity merge.
  • MERGE_SCORE_THRESHOLD (default: 0.95): Cosine similarity threshold for merging.
  • Exclusion settings: MERGE_EXCLUDE_* lists, private name exclusion, name length bounds, and custom patterns.
• Execution:
  • When enabled, merge runs within the graph creation/update flow (after entity extraction).
  • You can also run the standalone tool: uv run standalone_entity_merger.py <storage_dir_path>

Detailed Environment Variables

All environment variables and defaults can be configured by copying .env.example to .env.

🧬 Supported Languages (v0.2.2)

The following 13 languages are supported:

• Python
• C
• C++
• Rust
• C#
• Go
• Ruby
• Java
• Kotlin
• JavaScript
• TypeScript
• HTML
• CSS

🏗️ MCP Structure

repo-graphrag-mcp/
├── README.md
├── CHANGELOG.md              # Changelog
├── LICENSE                   # License (MIT)
├── pyproject.toml            # Package settings
├── server.py                 # MCP server entrypoint
├── .env.example              # Environment variable template
├── standalone_graph_creator.py   # Standalone graph builder
├── standalone_entity_merger.py   # Standalone entity merger
├── repo_graphrag/            # Package
│   ├── config/               # Configuration
│   ├── initialization/       # Initialization
│   ├── llm/                  # LLM clients
│   ├── processors/           # Analysis/graph building
│   ├── utils/                # Utilities
│   ├── graph_storage_creator.py  # Storage creation
│   └── prompts.py            # Prompts
└── logs/                     # Log output

🛠️ Standalone Execution

You can also run without an MCP client:

standalone_graph_creator.py - Build Knowledge Graph

Analyze a repository and create a knowledge graph:

uv run standalone_graph_creator.py <read_dir_path> <storage_name>

Examples:

uv run standalone_graph_creator.py /home/user/myproject my_storage
uv run standalone_graph_creator.py C:\\projects\\webapp webapp_storage

standalone_entity_merger.py - Entity Merge

Merge entities within an existing storage:

uv run standalone_entity_merger.py <storage_dir_path>

Examples:

uv run standalone_entity_merger.py /home/user/myproject/my_storage
uv run standalone_entity_merger.py C:\\projects\\webapp/webapp_storage

Note:

• The storage directory must be created beforehand by graph_create or standalone_graph_creator.py.

🔧 Technical Details

This MCP server uses LightRAG and Tree - sitter. LightRAG is utilized for building the knowledge graph and performing retrieval operations, while Tree - sitter is used for code parsing. The server interacts with various LLM providers through environment variables to handle different tasks such as knowledge graph creation, implementation planning, and Q&A.

The entity merge feature normalizes and filters entity names, embeds document and code entities, and uses cosine similarity to merge semantically similar entities. This helps in unifying references across code and documentation.

🙏 Acknowledgments

This MCP is built on the following libraries:

• LightRAG - GraphRAG implementation
• Tree - sitter - Code parsing

📄 License

This MCP is released under the MIT License. See the LICENSE file for details.