Codebase RAG MCP Server

An MCP (Model Context Protocol) server that gives Claude semantic search over a local codebase — find functions and classes by meaning, not just keyword matching.

Built with Python, FastMCP, tree-sitter, sentence-transformers, and ChromaDB.

What it does

Ask Claude Desktop things like:

-> "Index the codebase at C:\my-project, then find the function that handles user authentication"

Instead of exact-keyword grep, the server:

1. Parses your code with tree-sitter into an AST (Abstract Syntax Tree)
2. Splits it into chunks at function/class boundaries (not arbitrary line counts)
3. Embeds each chunk with a local sentence-transformer model — no API key, no cost
4. Stores embeddings in ChromaDB, a local vector database
5. Ranks results by semantic similarity to your query, so "authenticate a user" correctly surfaces a function named verify_login, even with zero shared words

Architecture

User → Claude Desktop → MCP Server (this project) │ ┌─────────┼─────────┐ │ │ │ indexer.py chunker.py vectorstore.py (find files) (AST chunk) (embed + store + search) │ ChromaDB (local, on disk)

Tools exposed

Tool	What it does
list_code_files	Lists all code files in a given repo path
read_file	Reads and returns a single file's contents
index_codebase	Chunks, embeds, and stores a repo's code for search
clear_codebase_index	Wipes the stored index (useful before re-indexing)
search_codebase	Semantic search over previously indexed code

Supported languages

Python, JavaScript, JSX, TypeScript, TSX — chunked at the function/class level via per-language tree-sitter grammars. Easy to extend: add a grammar + node-type mapping to LANGUAGES in chunker.py.

Setup

git clone <this-repo>
cd codebase-rag-mcp
python -m venv venv
venv\Scripts\Activate.ps1       # Windows
# source venv/bin/activate      # macOS/Linux

pip install -r requirements.txt

Connect to Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit config in Claude Desktop):

{
  "mcpServers": {
    "codebase-rag": {
      "command": "/absolute/path/to/codebase-rag-mcp/venv/Scripts/python.exe",
      "args": ["/absolute/path/to/codebase-rag-mcp/server.py"]
    }
  }
}

Restart Claude Desktop. Confirm it's running under Settings → Developer.

Example usage

You: Index the codebase at C:\my-project Claude: Indexed 47 code chunks from C:\my-project.

You: Search for code that sends emails Claude: [function] send_notification_email in mailer.py (lines 12-28, distance=0.31)

How chunking works

Instead of splitting files into fixed-size blocks of text (which can cut a function in half), this project parses each file into an AST and extracts whole functions/classes as chunks — using the actual grammar of each language via tree-sitter, not regex or heuristics.

Known limitations

• Stale chunks after edits: chunk IDs include the function's starting line number. If a file is edited and a function moves to a different line, the old chunk entry isn't automatically removed on re-index — only overwritten if the line number happens to match. Fix: delete all existing chunks for a file path before re-inserting on each index run.
• Truncates files/results over ~8000 characters to avoid flooding the conversation.
• No incremental indexing yet — every index_codebase call re-embeds all matching files, even unchanged ones.

Possible extensions

• Incremental re-indexing (only re-embed changed files, via file hash or mtime)
• .gitignore-aware file discovery
• More languages (Go, Rust, Java, C/C++)
• Cross-encoder re-ranking for higher precision on top results

Tech stack

• MCP / FastMCP — protocol + server framework for exposing tools to Claude
• tree-sitter — language-aware code parsing (AST-based chunking)
• sentence-transformers (all-MiniLM-L6-v2) — local embedding generation, no external API
• ChromaDB — local, persistent vector database