# mcp-codebase-index

Parses a codebase into functions, classes and dependencies, then hands the agent 18 query tools instead of full file reads.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 63
- Author: MikeRecognex
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/MikeRecognex/mcp-codebase-index
- Updated: 2026-02-28
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-codebase-index

## What it does

The server walks your sources and builds a structural index: functions, classes, imports, a dependency graph and cross-file call chains. Python goes through the `ast` module; TypeScript and JS, Go, Rust and C# are parsed with regexes. Markdown and text files yield sections from headings, everything else contributes line counts only. The agent then queries the index rather than opening files one by one.

In a git repository the index keeps itself current. Before every query the server checks `git diff` and `git status`, and re-parses only the files that changed. The index is stored in `.codebase-index-cache.pkl` at the project root: a matching git ref means instant startup, a small changeset means the cached index loads and updates incrementally. Add that file to `.gitignore` — it is a local build artifact.

Python 3.11+ is required. Install the package with the `[mcp]` extra, run it via `uvx` or as the `mcp_codebase_index.server` module, and point `PROJECT_ROOT` at the directory to index. Claude tends to reach for its built-in Glob, Grep and Read tools even when the server is configured, so a `.mcp.json` entry alone is not enough — project instructions or a `SessionStart` hook have to remind the agent to query the index first.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-codebase-index -- uvx mcp-codebase-index
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>

### Codex

**Platform CLI**
```bash
codex mcp add mcp-codebase-index -- uvx mcp-codebase-index
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-codebase-index": {
            "command": "uvx",
            "args": [
                "mcp-codebase-index"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-codebase-index": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "mcp-codebase-index"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-codebase-index uvx mcp-codebase-index
```
uvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>

## When to use it
- find every call site of a function without opening each file
- map module dependencies before a refactor
- list classes and interfaces in an unfamiliar repository
- keep the index fresh after a branch switch without a manual restart
- cut context size when navigating a large codebase

## Example prompts
- List every function in `src/api/` that calls `parse_config`
- Which modules depend on `db/session.py`?
- Find classes with a `handle` method under `services/`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md