# Codebase Brain (pypi · codebase-brain-mcp)

Cited, searchable memory of a codebase: hybrid search, git history, impact analysis, doc drift.

- Trust score: 74/100 (medium)
- Change this week: −11
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- pypi · `codebase-brain-mcp`: 74/100 (this document), [markdown](https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp.md), [page](https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp)

## Channel facts

- Registry: `pypi`
- Package: `codebase-brain-mcp`
- Version: `0.2.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 49/100
  - Malware scan not yet available for this package.
  - Known CVEs were checked across the 69 of 71 dependencies we could resolve, so this covers what we could see, not the whole tree.
  - Runs uv_build at install time, a recognised build step with no custom scripting around it.
  - Dependency health was assessed across the 69 of 71 dependencies we could resolve, so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to Nomannazir/codebase-brain-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 14 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 80/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 1453 tokens (~145/item across 10 items; 9 tools + 1 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 50/100
  - Stability observed for 15 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 9 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 11 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the Codebase Brain MCP server?

Codebase Brain runs locally as a PyPI package, launched with uvx codebase-brain-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add nomannazir-codebase-brain-mcp -- uvx codebase-brain-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "nomannazir-codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "nomannazir-codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add nomannazir-codebase-brain-mcp -- uvx codebase-brain-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nomannazir-codebase-brain-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "codebase-brain-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add nomannazir-codebase-brain-mcp --command uvx --arg codebase-brain-mcp
```

### Hermes

```yaml
mcp_servers:
  nomannazir-codebase-brain-mcp:
    command: "uvx"
    args: ["codebase-brain-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "nomannazir-codebase-brain-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "codebase-brain-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add nomannazir-codebase-brain-mcp -t stdio -c uvx -a codebase-brain-mcp
```

### Other

```json
{
  "mcpServers": {
    "nomannazir-codebase-brain-mcp": {
      "command": "uvx",
      "args": [
        "codebase-brain-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 74, +1)

No change was recorded against any check on this day. Stability & Change Management went from 47 to 50. That category is still filling its 30-day observation window: 14 days of observed history at the previous scan, 15 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-19 (score 73, +1)

No change was recorded against any check on this day. Stability & Change Management went from 40 to 43. That category is still filling its 30-day observation window: 12 days of observed history at the previous scan, 13 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-17 (score 72, −14)

- [security regression] Malware scan: pass → unverified

### 2026-11-15 (score 86, +1)

No change was recorded against any check on this day. Stability & Change Management went from 27 to 30. That category is still filling its 30-day observation window: 8 days of observed history at the previous scan, 9 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-13 (score 85, +1)

No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-12 (score 84, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-11 (score 69, −14)

- [security regression] Malware scan: pass → unverified

### 2026-11-10 (score 83, +15)

- [security improvement] Malware scan: unverified → pass

## MCP tools (9)

### `index_repo` (~119 tokens)

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.

Input parameters:

- `name`: Name to index it under. Defaults to the folder or repository name.
- `source` (string, required): A local directory, or an https git URL such as https://github.com/owner/repo.

Output parameters:

- `chunks_total` (integer)
- `commit`
- `commits_added` (integer)
- `commits_total` (integer)
- `files_indexed` (integer): Files embedded this run (new or changed).
- `files_removed` (integer)
- `files_seen` (integer)
- `files_unchanged` (integer)
- `full_rebuild` (boolean)
- `repo` (string)
- `root` (string)
- `seconds` (number)

### `search` (~195 tokens)

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.

Input parameters:

- `k` (integer): How many results to return, 1 to 25.
- `kinds`: Only these chunk kinds: function, class, method, interface, type, enum, module, section (docs) or code (other files).
- `path_prefix`: Only consider files under this path, e.g. "src/auth/" or "docs/".
- `query` (string, required): An identifier (normalizeRetryOptions) or plain words.
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.

Output parameters:

- `query` (string)
- `repo` (string)
- `results` (array)

### `ask_codebase` (~146 tokens)

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.

Input parameters:

- `k` (integer): How many results to return, 1 to 25.
- `question` (string, required): A question in plain words, e.g. "How are sessions expired?"
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.

Output parameters:

- `instructions` (string)
- `question` (string)
- `related_commits` (array): Commits whose messages match the question.
- `repo` (string)
- `sources` (array)

### `explain_history` (~206 tokens)

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).

Input parameters:

- `end_line`: Last line of the range (with path).
- `max_commits` (integer): How many commits to return, newest first.
- `path`: A file in the repo. Narrow it with start_line and end_line.
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.
- `start_line`: First line of the range (with path).
- `symbol`: A function, class or method, e.g. "unsign" or "Signer.sign". Use this or path.

Output parameters:

- `authorship` (array)
- `changes` (array): Commits that changed these lines, newest first.
- `citation` (string)
- `instructions` (string)
- `pull_requests` (array)
- `repo` (string)
- `symbol`

### `impact_of_change` (~174 tokens)

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.

Input parameters:

- `depth` (integer): 1 = direct users only; 2 or 3 also follows users of those users.
- `path`: The file that defines symbol, when several files define that name.
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.
- `symbol` (string, required): The function, class or method you plan to change, e.g. "discount" or "Cart.total".

Output parameters:

- `direct` (array)
- `indirect` (array)
- `notes` (array)
- `same_name_definitions` (array)
- `summary` (string)
- `symbol` (string)
- `target` (string): path:start-end of the definition analysed.
- `tests` (array): Citations of tests that exercise the target, directly or not.

### `find_doc_drift` (~179 tokens)

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.

Input parameters:

- `check_history` (boolean): Also flag doc sections last edited long before the code they describe.
- `limit` (integer): Most findings to return, 1 to 200, most severe first.
- `path_prefix`: Only consider files under this path, e.g. "src/auth/" or "docs/".
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.

Output parameters:

- `findings` (array)
- `references_checked` (integer)
- `repo` (string)
- `sections_checked` (integer)
- `summary` (string)

### `search_history` (~120 tokens)

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.

Input parameters:

- `k` (integer): How many results to return, 1 to 25.
- `query` (string, required): Words from commit messages, e.g. "fix timezone" or "drop python 3.8".
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.

Output parameters:

- `result` (array)

### `read_lines` (~124 tokens)

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.

Input parameters:

- `end` (integer, required): Last line to return (inclusive).
- `path` (string, required): The file, relative to the repo root, as a citation shows it.
- `repo`: Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed.
- `start` (integer, required): First line to return (1-based).

Output parameters:

- `result` (string)

### `list_repos` (~46 tokens)

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.

Output parameters:

- `result` (array)

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp#diagnostics

## Score history

- 2026-11-21: 74
- 2026-11-20: 73
- 2026-11-19: 73
- 2026-11-18: 72
- 2026-11-17: 72
- 2026-11-16: 86
- 2026-11-15: 86
- 2026-11-14: 85
- 2026-11-13: 85
- 2026-11-12: 84
- 2026-11-11: 69
- 2026-11-10: 83
- 2026-11-09: 68
- 2026-11-08: 82
- 2026-11-07: 82
- 2026-11-06: 63

## Common questions

### What is the Codebase Brain MCP server?

Codebase Brain is an MCP server listed in the public MCP registry as io.github.Nomannazir/codebase-brain-mcp. Cited, searchable memory of a codebase: hybrid search, git history, impact analysis, doc drift. This page covers its PyPI package (codebase-brain-mcp).

### Is the Codebase Brain MCP server safe to use?

Codebase Brain scores 74 out of 100 on VerifyMCP. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Codebase Brain MCP server expose?

Codebase Brain exposes 9 tools: index_repo, search, ask_codebase, explain_history, impact_of_change, and 4 more. Their descriptions and schemas cost roughly 1,309 tokens of context every time the server is loaded.

### Is the Codebase Brain MCP server still maintained?

Codebase Brain is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Codebase Brain MCP server under?

Codebase Brain declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the Codebase Brain MCP server?

VerifyMCP ran 15 checks on Codebase Brain, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about Codebase Brain: Malware scan. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- PyPI project: https://pypi.org/project/codebase-brain-mcp/
- Socket report: https://socket.dev/pypi/package/codebase-brain-mcp
- Repository: https://github.com/Nomannazir/codebase-brain-mcp
- Changelog RSS feed: https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp.json
- HTML version of this page: https://verifymcp.io/servers/nomannazir-codebase-brain-mcp/codebase-brain-mcp
