Codebase Q&A MCP Server

An MCP server that lets AI assistants answer questions about any codebase using RAG (Retrieval-Augmented Generation). Index any git repository locally, then ask natural-language questions — answers are grounded in actual source code.

Built with FastMCP, ChromaDB, and sentence-transformers.

How It Works

┌─────────────┐     ┌──────────────────────────────────────────────┐
│  AI Client   │     │         Codebase Q&A MCP Server              │
│ (Claude Code,│ MCP │                                              │
│  Claude      │◄───►│  ┌─────────┐  ┌──────────┐  ┌───────────┐  │
│  Desktop,    │     │  │  Load &  │─►│ Embed    │─►│ ChromaDB  │  │
│  Cursor)     │     │  │  Chunk   │  │(MiniLM)  │  │ (persist) │  │
│              │     │  └─────────┘  └──────────┘  └───────────┘  │
└─────────────┘     └──────────────────────────────────────────────┘

1. Index — Point the server at a git repo. It reads all source files, splits them into chunks, generates embeddings with all-MiniLM-L6-v2, and stores them in a persistent ChromaDB instance.
2. Query — Ask a natural-language question. The server finds the most relevant code chunks via semantic similarity and returns them with file paths and metadata.
3. Update — After new commits, run an incremental update that only re-indexes changed files (using git diff).

Features

• 7 MCP tools for full codebase Q&A workflow
• Local embeddings — no API keys needed (runs all-MiniLM-L6-v2 on your machine)
• Persistent storage — ChromaDB persists indexes across sessions
• Incremental updates — only re-index files that changed since last commit
• Multi-project support — index multiple repos and switch between them
• File filtering — narrow queries to specific paths (e.g. only auth-related files)
• 30+ file types supported (Python, JS/TS, Go, Rust, Java, C/C++, Markdown, YAML, SQL, and more)

Installation

Option 1: uvx (recommended)

uvx codebase-qa-mcp

Option 2: pip

pip install codebase-qa-mcp

Option 3: From source

git clone https://github.com/gokul-viswanathan/codebase-qa-mcp.git
cd codebase-qa-mcp
pip install -e .

Option 4: agentregistry

# Install arctl
curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash

# Deploy the server
arctl deploy codebase-qa-mcp

# Auto-configure your IDE
arctl configure claude-desktop

Quick Start

1. Add to Claude Code

claude mcp add codebase-qa-mcp -- codebase-qa-mcp

Or if running from source:

claude mcp add codebase-qa-mcp -- /path/to/codebase-qa-mcp/.venv/bin/python -m codebase_qa_mcp.server

2. Add to Claude Desktop

Add this to your Claude Desktop config (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "codebase-qa-mcp": {
      "command": "codebase-qa-mcp",
      "args": []
    }
  }
}

Or from source:

{
  "mcpServers": {
    "codebase-qa-mcp": {
      "command": "/path/to/codebase-qa-mcp/.venv/bin/python",
      "args": ["-m", "codebase_qa_mcp.server"]
    }
  }
}

3. Use it

Once connected, your AI assistant can use these tools:

You: "Index the repo at /home/user/my-project"
AI:  → calls index_repository("/home/user/my-project")
     ✓ Indexed 42 files → 380 chunks

You: "How does authentication work in this codebase?"
AI:  → calls query_codebase("how does authentication work")
     Returns relevant code chunks from auth-related files

You: "What files handle database migrations?"
AI:  → calls query_codebase("database migrations", file_filter="migrations")
     Returns chunks specifically from migration files

MCP Tools Reference

Tool	Description
index_repository	Full-index a git repo into ChromaDB. Reads all source files, chunks, embeds, and stores them.
update_index	Incrementally update using git diff. Only re-indexes changed files.
query_codebase	Semantic search for code chunks relevant to a natural-language question.
switch_project	Switch to a previously indexed repo without re-indexing.
list_indexed_files	List all file paths in the current project's index.
get_index_stats	Get stats: total chunks, total files, last indexed commit.
list_projects	List all previously indexed repositories.

Configuration

The server uses sensible defaults but you can customize via environment variables:

Variable	Default	Description
CODEBASE_QA_CHROMA_PATH	~/.local/share/codebase-qa-mcp/chroma_db	Where ChromaDB stores its data

Built-in defaults:

• Chunk size: 500 characters with 50-character overlap
• Embedding model: all-MiniLM-L6-v2 (384-dimensional, runs locally)
• Top-K results: 5

Project Structure

codebase-qa-mcp/
├── pyproject.toml                  # Package config, deps, entry point
├── Dockerfile                      # Container build for agentregistry
└── src/codebase_qa_mcp/
    ├── __init__.py
    ├── config.py                   # Constants (chunk size, model, extensions)
    ├── indexer.py                  # Load → chunk → embed → store + incremental updates
    ├── retriever.py                # Query, list files, stats, list projects
    └── server.py                   # FastMCP server with 7 tools

How RAG Works Here

Retrieval-Augmented Generation (RAG) grounds AI responses in actual source code rather than relying on the model's training data:

1. Chunking — Source files are split into ~500-character chunks using RecursiveCharacterTextSplitter from LangChain, which respects code boundaries.
2. Embedding — Each chunk is converted to a 384-dimensional vector using all-MiniLM-L6-v2, a fast sentence-transformer model that runs entirely on your machine.
3. Storage — Vectors are stored in ChromaDB with metadata (file path, chunk index, language). The database persists to disk so indexes survive restarts.
4. Retrieval — When you ask a question, it's embedded with the same model and compared against stored chunks via cosine similarity. The top-K most relevant chunks are returned.
5. Generation — The AI client (Claude, etc.) receives the relevant code chunks and uses them to generate an accurate, grounded answer.

License

MIT