mcp-codebase-index

The mcp-codebase-index server is a structural codebase indexer exposed over MCP to let clients navigate large codebases efficiently. It parses source files to extract structural metadata such as functions, classes, imports, and dependency relationships, then exposes 18 query tools via MCP to help tools like Claude Code or other MCP clients understand and traverse a project without reading every file. The server also keeps an automatic, incremental re-index as you work: before every query it checks the git working state and only reprocesses changed files, ensuring the index stays current with minimal overhead. A persistent on-disk cache (.codebase-index-cache.pkl) speeds up restarts; if the cached state matches the current HEAD, startup is nearly instant. This makes frequent code navigation fast in environments like OpenClaw or Claude Code where you want reliable, fast access to code structure rather than raw file contents.

To use it, install the package with MCP support, run the server pointing at a project root, and connect via a compatible MCP client. OpenClaw users can install the package locally and add the MCP server entry under the openclaw.json config, after which all 18 tools (e.g., find_symbol, get_function_source, search_codebase, get_dependencies) become available to your agent. The server is designed to work with Python projects and is language-aware for Python, TypeScript/JS, Go, Rust, C#, Markdown/Text, and more, providing targeted extraction per language and incremental caching to minimize downtime during development.

Prerequisites:

• Python 3.11+ installed on your system
• pip available in your environment

Install the MCP-enabled package:

pip install "mcp-codebase-index[mcp]"

The [mcp] extra includes the MCP server dependency. Omit it if you only need the library APIs.

For development from a local clone:

pip install -e ".[dev,mcp]"

If you want to run the server via a module entry point (as described in the MCP docs), ensure you have the project checked out and then you can start indexing by setting PROJECT_ROOT and invoking the entry point as shown in the next section.

Notes and tips:

• The server caches the index to .codebase-index-cache.pkl in the project root. Add this to your .gitignore to avoid committing the cache. A cache hit keeps startup fast and avoids full reindexing.
• Before querying, the server checks git diff/status to determine what changed and reindexes only those files when needed.
• Configure the MCP server in Claude Code or Claude-compatible clients by providing an mcpServers entry with command mcp-codebase-index and the PROJECT_ROOT environment variable.
• If using Docker/OpenClaw environments, install the package inside the target environment and set PROJECT_ROOT to the directory you want to index within that environment.
• For persistent connections, consider using plugins that maintain a single server process to benefit from in-memory index availability and avoid repeated startup overhead.
• This server supports multiple languages via language-specific extractors (Python AST, regex-based parsers for TS/JS, Go, Rust, C#, and more). The toolset includes 18 MCP-owned queries for thorough codebase navigation.