repo-graphrag

This MCP server, Repo GraphRAG, builds and queries a knowledge graph from code and text documents within a repository or directory. It uses LightRAG and Tree-sitter to extract structure and content, then creates an embedding index for fast retrieval. The server exposes three main MCP tools: graph_create for building or updating the graph, graph_plan for generating implementation plans and concrete steps, and graph_query for question-and-answer interactions based on the graph. Clients can connect using any MCP-compatible client, including Claude-based tooling, VS Code extensions, or generic MCP libraries. To use, start the server with the uv command provided in the README, then issue commands starting with graph: and specifying the target directory and storage name (default storage is storage or the specified storage).

• graph_create analyzes the target directory to build or incrementally update the knowledge graph and embeddings. It supports incremental updates by reanalyzing only changes when the same storage name is used. You can adjust extraction settings and embeddings by changing environment variables and model names.
• graph_plan uses the knowledge graph to generate a detailed implementation plan and actionable steps for a requested modification or enhancement, optionally combining results with vector search for improved accuracy.
• graph_query answers questions about the repository based on the graph and, if configured, vector search. It can explain architecture, endpoints, or design decisions derived from the graph content.

Prerequisites

• Python 3.11+
• uv package manager
• Access/keys for your preferred LLM provider (Anthropic, OpenAI, Gemini, or Azure OpenAI)
• Git

Install and run locally

1. Clone the repository

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

2. Install dependencies via uv (the MCP client/server manager)

uv sync

3. Prepare environment

# Copy the settings file (adjust paths as needed)
cp .env.example .env

# Edit the .env file to configure providers, models, and keys
nano .env

4. Run the MCP server

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

5. Optional: Integrate with an MCP client (Claude, VS Code, etc.) using the examples provided in the README to register the server and start issuing graph: commands.

Tips and notes:

• If you change the embedding model or DOC extraction settings, you may need to rebuild the storage. You can either delete the existing storage or provide a new storage name when running graph_create.
• The first graph creation can take longer as large repos are processed; for very large repos, consider targeting a smaller subset or directory.
• Embedding caches are downloaded automatically on first use; ensure network access and necessary authentication tokens are available.
• For local testing with OpenAI-compatible endpoints, you can set OPENAI_BASE_URL to point to a local server (e.g., LM Studio) if you’re using an OpenAI-compatible interface.
• The MCP supports both incremental updates and full rebuilds; use storage naming to control whether a rebuild overwrites or extends existing data.
• If issues arise, check the .env file validity, ensure API keys are correct, and confirm the uv server is reachable by your MCP client.