Purpose
mcp-codebase-index is a structured codebase indexer that also provides an MCP (Model Context Protocol) server for AI-assisted development scenarios, helping AI navigate a codebase in a structured way. Its core goal is not to answer "where is a certain function", but rather "what will happen if I change it".
Main Capabilities
- Parses source code into structured metadata: functions, classes, imports, dependency graphs, and cross-file call chains.
- Exposes 18 query tools through MCP for Claude Code and other MCP clients to call, avoiding reading entire files.
- Zero runtime dependencies: Python analysis uses Python's ast module, while TypeScript/JS, Go, Rust, and C# use regex-based parsing. Requires Python 3.11+.
- Automatic incremental reindexing: in a git repository, checks git diff and git status before each query (about 1-2ms); if files have changed, only re-parses the changed files and rebuilds the dependency graph, with no manual reindex needed.
- Persistent disk cache: after each build, the index is saved to the pickle cache file .codebase-index-cache.pkl; on subsequent startup it is verified against the current git HEAD, and if the ref matches, startup is instantaneous; when there are ≤20 changed files, the cache is loaded and incrementally updated rather than fully rebuilt.
- Built-in token budget control: parameters such as max_results and max_lines mean response size grows with the answer rather than the size of the codebase.
Usage
Installation (including MCP server dependencies): use the install command with the [mcp] extra; if you only need the programmatic API, you can omit that extra. During development, you can also install from a local clone. PROJECT_ROOT specifies the directory to index, defaulting to the current working directory.
Persistent cache behavior: on a cache hit (exact match), if the cached git ref matches the current HEAD, load directly from disk; on a cache hit (small changeset), if there are ≤20 changed files, load the cache and incrementally update on the first query; on a cache miss, perform a full rebuild and save a new cache. It is recommended to add .codebase-index-cache.pkl to .gitignore.
Configuration with OpenClaw:Install the package on the machine running OpenClaw, add the MCP server to OpenClaw's openclaw.json, restart and verify the connection, and all 18 tools are available. Note: by default, OpenClaw's MCP integration via mcporter creates a new server process for each tool call, discarding the in-memory index and forcing a rebuild; a persistent cache can significantly speed up such cold starts. If a persistent connection is needed, the openclaw-mcp-adapter plugin can be used.
Configuration with Claude Code: add the configuration to the project's .mcp.json, or use the Python module directly (suitable when installed in a virtualenv). Claude Code by default tends to use the built-in Glob/Grep/Read tools; in addition to the CLAUDE.md instructions, hooks that trigger on every prompt can be added to reinforce the behavior (SessionStart triggers on startup, resume, and context compaction; UserPromptSubmit triggers every turn).
Important note: by default, the AI assistant will ignore the index tools and fall back to reading entire files; mandatory wording should be used rather than soft phrasing like "prefer", and clear fallback conditions should be given.
Use cases
Suitable for AI-assisted codebase navigation and refactoring analysis, such as querying symbols, classes, and import relationships, assessing the direct and transitive impact of a change to a symbol (get_change_impact found 154 direct dependencies and 492 transitive dependencies on CPython, taking 0.45ms), and controlling the AI's token consumption in large codebases.
Performance
Tested on four real projects on an M-series MacBook Pro, covering small projects up to the 1.1-million-line CPython. Multiple targeted queries still return at sub-millisecond speed on CPython; find_symbol returns 54-67 characters whether the project is 7K lines or 1.1 million lines. Output can be limited using max_direct and max_transitive. With a persistent cache, a CPython cache hit can restore the full index in under 1 second instead of 56 seconds. Benchmarks can be run via python benchmarks/benchmark.py.
Differences from LSP
LSP answers "where is this function", while mcp-codebase-index answers "what happens if I change it". LSP is a point query: one symbol, one file, one location; it cannot directly answer "what is transitively affected after refactoring a symbol". This tool can return direct and transitive impact in a single call (example: 11 direct dependencies, 31 transitive impacts, 204 characters). LSP also requires installing a separate language server for each language (such as pyright, vtsls, gopls), whereas this tool has zero dependencies and supports Python, TypeScript/JS, Go, Rust, C#, and Markdown out of the box, with built-in token budget control for every response.
Limitations
Requires Python 3.11+. Uses regex-based parsing for TypeScript/JS, Go, Rust, and C#. Cache files are local build artifacts and should be added to .gitignore. If embedded in a proprietary product or offered as a hosted service, a commercial license is required.
License and origin
This project is dual-licensed: open-source use is AGPL-3.0 (see LICENSE), and proprietary use is under a commercial license (see COMMERCIAL-LICENSE.md). Using it as a standalone MCP server for development is covered by AGPL-3.0 at no cost. The structured indexer was originally developed as part of the RMLPlus project (an implementation of the Recursive Language Models framework).
