mcp-codebase-index — Claude Code MCP server: code index
Parses a codebase into functions, classes and dependencies, then hands the agent 18 query tools instead of full file reads.
claude mcp add mcp-codebase-index -- uvx mcp-codebase-indexWhat mcp-codebase-index 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.
What it helps with
- 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 for the agent
- List every function in
src/api/that callsparse_config - Which modules depend on
db/session.py? - Find classes with a
handlemethod underservices/
How to install mcp-codebase-index
Platform CLI
claude mcp add mcp-codebase-index -- uvx mcp-codebase-indexuvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>
Platform CLI
codex mcp add mcp-codebase-index -- uvx mcp-codebase-indexuvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add mcp-codebase-index uvx mcp-codebase-indexuvx runs the command named after the package; if the README names another one, use uvx --from mcp-codebase-index <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-codebase-index
How do I install mcp-codebase-index in Claude Code?
Install the package first: pip install "mcp-codebase-index[mcp]". Then register the server with claude mcp add mcp-codebase-index -- uvx mcp-codebase-index.
What does mcp-codebase-index do?
It indexes source files into structural metadata — functions, classes, imports, dependencies — and exposes query tools over that index. The agent can locate code without reading whole files.
Does the server need git?
No, but automatic re-indexing works in git repositories, where the server checks git diff and git status before each query. Outside git you rebuild the index yourself.
