Codebase Brain

Codebase Brain MCP

An MCP server that gives AI assistants a cited, searchable memory of a codebase, including its history. Point it at a local folder or a public git URL. Claude, Cursor or any MCP client can then answer questions about the code with exact path:start-end citations.

*Claude Code asks why TimestampSigner.unsign looks the way it does, what breaks if it changes, and whether its docs are current. Codebase Brain answers with commits, callers, tests and doc findings, all cited. (Waiting time sped up.)*

The problem

AI coding assistants are good at writing new code but struggle to understand code that already exists:

• They can't see the whole project. A real codebase has thousands of files. The assistant reads a few and guesses the rest, so it misses the function that matters or invents one that doesn't exist.
• You can't check their answers. "Expiry is handled in the auth module" is no use if you can't see where. Without file and line references, you have to trust the answer or re-read the code yourself.
• They don't know why code is the way it is. The code shows *what* it does. The reasons ("we added this check because it crashed on Windows") live in git history and pull requests, which assistants never read. So they "clean up" code that exists for a reason and bring old bugs back.
• They don't know what a change will break, or whether the documentation still matches the code.
• Many tools send your code to someone else's server to make it searchable.

What Codebase Brain gives you

A plug-in for any AI assistant that turns a codebase into something it can actually look things up in:

• Answers with proof. Every result points to the exact file and lines, and the assistant can open them.
• Search that understands code. It finds code whether you type the exact name (calculate_invoice_total) or describe it in plain words ("how are invoices totalled?").
• The story behind the code. For any function, it shows every change made to it, who made it, why (from the commit message and pull request), and what the change was.
• What breaks if you change something. Everything that uses a function, directly or indirectly, and the tests that cover it.
• Out-of-date docs, found automatically. Documentation that mentions functions, files or settings that no longer exist, or shows examples that would no longer work.
• Private by design. Everything runs on your machine. No API keys, and your code never leaves your computer.

Why it's different (technical)

• Code-aware chunking. Python is split by function, class and method using the real syntax tree, Markdown by heading. Each chunk knows its symbol (TimestampSigner.unsign) and exact lines, so citations point at real code.
• Hybrid retrieval. SQLite FTS5 BM25 (with camelCase / snake_case identifier splitting) plus local embeddings, merged with reciprocal-rank fusion. Exact names and fuzzy questions both work.
• Local and free. Embeddings run on your machine (fastembed, ONNX). No API keys, and no code leaves your computer.
• Incremental. Re-indexing only re-embeds files whose content changed. On a 42-file repo, a re-index with no changes takes about 2 seconds.
• History-aware. explain_history follows a function's lines back through git (git log -L), shows who wrote the current lines, and links the pull requests behind each change. So agents can answer *"why is it built this way?"*, not just *"what does it do?"*.
• Impact analysis. impact_of_change lists everything that uses a function, directly and transitively, plus the tests that exercise it, before an agent changes anything.
• Doc-drift detection. find_doc_drift checks Markdown and reStructuredText docs against the code. It finds files, functions, settings and flags that don't exist; examples passing parameters a function doesn't take; imports that would fail; and sections last edited long before the code they describe changed. Each finding cites the doc section and suggests a fix ("Was it renamed to checkout_total?").
• Agent-friendly output. Structured tool results, read-only tool annotations, progress notifications while indexing, and clear error messages the model can act on.

Tools

Also included: the resource brain://repos, and the prompt answer_with_citations.

Install

Codebase Brain runs on your own machine, so there's no server or account, and it's free. With uv:

# Claude Code

claude mcp add codebase-brain -- uvx codebase-brain-mcp

Any MCP client (Claude Desktop, Cursor, ...): add this server to its config

{ "command": "uvx", "args": ["codebase-brain-mcp"] }

Quick start

uv sync

uv run codebase-brain index https://github.com/pallets/itsdangerous uv run codebase-brain search "how is the signature timestamp checked for expiry"

0.0313 src/itsdangerous/timed.py:72-158 method TimestampSigner.unsign 0.0311 docs/timed.rst:1-28 code 0.0301 src/itsdangerous/timed.py:170-228 class TimedSerializer

Ask why it looks like that. explain_history(symbol="TimestampSigner.unsign") returns its line-by-line history:

src/itsdangerous/timed.py:72-158

3edfbbbc 2022-03-24 handle OverflowError in timed unsign on 32-bit systems 177196d3 2022-03-09 catch OSError on Windows 37f09970 2022-03-08 catching year overflow ValueError c30678d1 2019-05-31 don't allow timestamps from the future 910a7a94 2020-04-17 datetimes are timezone-aware utc ...

Use it from Claude Code

claude mcp add codebase-brain -- uv run --directory /path/to/codebase-brain-mcp codebase-brain

Run it as a remote server (Streamable HTTP)

export CODEBASE_BRAIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

uv run codebase-brain serve --transport streamable-http --host 0.0.0.0 --port 8765

Clients connect to http:// :8765/mcp with Authorization: Bearer . GET /healthz is open for load balancers. Remote mode is locked down by default:

• No token, no public port. The server refuses to listen beyond localhost without a token of at least 24 characters. Tokens are compared in constant time.
• Remote clients can't read the server's disk. Only public https:// git URLs can be indexed, not local paths, unless you set CODEBASE_BRAIN_ALLOW_LOCAL_PATHS=1.
• Big repos are refused above CODEBASE_BRAIN_MAX_FILES (default 20,000), and every git command has a timeout.
• DNS-rebinding protection is on for localhost, and for any hosts listed in CODEBASE_BRAIN_ALLOWED_HOSTS.

Docker

docker build -t codebase-brain-mcp .

docker run -p 8765:8765 -e CODEBASE_BRAIN_TOKEN="$CODEBASE_BRAIN_TOKEN" -v brain-data:/data codebase-brain-mcp

The image runs as a non-root user and includes the embedding model, so it starts fast and needs no download at runtime. It has a health check, and keeps indexes in the /data volume. Indexing uses about 1.2 GB of memory, so give the container 2 GB.

Configuration

Doc drift, tested honestly

On a well-maintained project (itsdangerous), find_doc_drift reports no false alarms. It only reports three "worth a look" sections whose docs date from 2020 while the code they describe changed in 2024–2025. On docs with planted mistakes, it catches every one: a moved file, a renamed function (with the right suggestion), an unknown setting and flag, a keyword argument the function doesn't take, and an import that would fail. Changelogs are skipped, because they're supposed to mention removed things.

Evaluation

Does search actually put the right code in front of the model? codebase-brain eval answers that with a benchmark. The benchmark has 32 questions about pallets/itsdangerous, pinned to commit 672971d, each with the code or docs a good answer must come from. The questions are in evals/datasets/itsdangerous.toml. They were written by reading the code before any results were measured, and haven't been changed since.

What this shows:

• Hybrid finds a right answer in the top 3 for 88% of questions, against 75% and 72% for either method alone. The gain comes from questions written in plain words and questions about the docs. When the question names the code, every mode finds it.
• **It's h