# Codebase Brain MCP server

> Provides AI assistants with a searchable, cited memory of a codebase including git history, impact analysis, and documentation drift detection.

- Repository: https://github.com/Nomannazir/codebase-brain-mcp
- Page: https://hostedmcp.org/servers/nomannazir/codebase-brain-mcp
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.2.1

## Install

### Claude Code

```sh
claude mcp add --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' codebase-brain-mcp -- uvx codebase-brain-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "codebase-brain-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"codebase-brain-mcp","type":"stdio","command":"uvx","args":["codebase-brain-mcp"],"env":{"GITHUB_TOKEN":"<YOUR_GITHUB_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add codebase-brain-mcp --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' -- uvx codebase-brain-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.codebase-brain-mcp]
command = "uvx"
args = ["codebase-brain-mcp"]

[mcp_servers.codebase-brain-mcp.env]
GITHUB_TOKEN = "<YOUR_GITHUB_TOKEN>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' codebase-brain-mcp uvx -- codebase-brain-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GITHUB_TOKEN` | no | yes | Optional. Raises GitHub's rate limit when reading pull request titles and descriptions. |
| `CODEBASE_BRAIN_HOME` | no | no | Where indexes and clones are stored (default ~/.codebase-brain). |
| `CODEBASE_BRAIN_TOKEN` | no | no |  |

## Tools (9)

- `index_repo`: Index a repository so the other tools can search it. Use this first, and again after the code changes: re-running only re-embeds files whose content changed. A URL is cloned with full history (blobless), so explain_history works. Reports progress while it runs, and returns file counts and the commit indexed.
- `search`: Hybrid search over code and docs (BM25 keywords plus local embeddings, fused by rank). Use this for a targeted lookup, or when you need filters by folder or chunk kind; for a question you'll answer in prose, use ask_codebase instead. Returns ranked chunks, each with a path:start-end citation, its symbol and a snippet. (read-only)
- `ask_codebase`: Gather the code and docs most relevant to a question, plus related commits, as numbered, cited sources. Use this to answer "how does X work?" or "where is Y handled?" questions. Answer from these sources only and cite each claim as path:start-end; open a source in full with read_lines. For filters, use search. (read-only)
- `explain_history`: Why code looks the way it does. Use this before removing or rewriting code that looks odd, or to answer "why is it like this?". Give a symbol, or a path with an optional line range. Returns who wrote the current lines, every commit that changed them (with the relevant diff), and the title and description of the pull request behind each commit (GitHub only). (read-only)
- `impact_of_change`: What breaks if a symbol changes: code that uses it directly, code that uses that code, and the tests involved. Use this before editing a shared function, and run or update the tests it lists. Python, JavaScript and TypeScript are analysed structurally. Matches are by name, so check the same-name notes it returns. (read-only)
- `find_doc_drift`: Documentation that no longer matches the code. Use this to check a README or docs folder, or before a release. Finds files, functions, settings and flags that don't exist; code examples that pass parameters a function doesn't take; imports that would fail; and stale sections. Each finding has a severity, cites the doc section and suggests a fix. Changelogs are skipped. (read-only)
- `search_history`: Find commits by what their messages say. Use this to answer "when did we change X?" or "which commit fixed Y?". For the history of one function or file, use explain_history instead. (read-only)
- `read_lines`: Exact, numbered lines from a file in an indexed repo. Use this to open a citation in full before quoting or editing it, since search results are trimmed snippets. Refuses paths outside the repo. (read-only)
- `list_repos`: Repositories indexed so far, with their size, languages and the commit they were indexed at. Use this first to see what's available and to get the repo names the other tools take. (read-only)

## FAQ

### Is my code private?

Yes, everything runs on your machine. No API keys are required, and your code never leaves your computer.

### Can it explain why code was written a certain way?

Yes, it can follow a function's history through git to show who changed it, why they changed it via commit messages, and link to pull requests.

### How does it handle documentation updates?

It features doc-drift detection which identifies documentation that no longer matches the code, such as missing functions or incorrect examples.

### What happens if I change a function?

The impact analysis tool lists everything that uses a function, both directly and indirectly, as well as the tests that cover it.
