Mcp Codebase Index
About
17 MCP query tools for codebase navigation — functions, classes, imports, dependency graphs, change impact. Zero dependencies. 87% token reduction.
Details
- License
- AGPL-3.0
Explore
- Zero runtime dependencies (only Python 3.11+)
- Automatic incremental re-indexing using git diff
- Persistent disk cache for instant startup
- 18 query tools including dependency graph and call chains
- Supports Python (AST), TypeScript/JS, Go, Rust, C# (regex)
- Sub-millisecond query times even on codebases over 1M lines
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Mcp Codebase IndexCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
pip install "mcp-codebase-index[mcp]"
The [mcp] extra includes the MCP server dependency. Omit it if you only need the programmatic API.
For development (from a local clone):
pip install -e ".[dev,mcp]"
Install the package on the machine where OpenClaw is running:
pip install "mcp-codebase-index[mcp]"
Add to your project's .mcp.json:
{
"mcpServers": {
"codebase-index": {
"command": "mcp-codebase-index",
"env": {
"PROJECT_ROOT": "/path/to/project"
}
}
}
}
Or using the Python module directly (useful if installed in a virtualenv):
{
"mcpServers": {
"codebase-index": {
"command": "/path/to/.venv/bin/python3",
"args": ["-m", "mcp_codebase_index.server"],
"env": {
"PROJECT_ROOT": "/path/to/project"
}
}
}
}
Claude Code tends to default to built-in Glob/Grep/Read tools even when codebase-index is available. In addition to CLAUDE.md instructions (see below), you can add hooks that fire on every prompt to reinforce the behavior. Add this to .claude/settings.local.json:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'CRITICAL REMINDER: Use codebase-index MCP tools FIRST for ALL code navigation (find_symbol, get_function_source, search_codebase, get_dependencies, etc). Only fall back to Glob/Grep/Read for non-code files.'"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Use codebase-index MCP tools first for code navigation.'"
}
]
}
]
}
}
Hook stdout is injected as context Claude sees before responding. SessionStart fires on startup, resume, and context compaction. UserPromptSubmit fires on every turn.
from mcp_codebase_index.project_indexer import ProjectIndexer
from mcp_codebase_index.query_api import create_project_query_functions
indexer = ProjectIndexer("/path/to/project", include_patterns=["*/.py"])
index = indexer.index()
query_funcs = create_project_query_functions(index)
get_project_summary
File count, packages, top classes/functions
list_files
List indexed files with optional glob filter
get_structure_summary
Structure of a file or the whole project
get_functions
List functions with name, lines, params
get_classes
List classes with name, lines, methods, bases
get_imports
List imports with module, names, line
get_function_source
Full source of a function/method
get_class_source
Full source of a class
find_symbol
Find where a symbol is defined (file, line, type)
get_dependencies
What a symbol calls/uses
get_dependents
What calls/uses a symbol
get_change_impact
Direct + transitive dependents
get_call_chain
Shortest dependency path (BFS)
get_file_dependencies
Files imported by a given file
get_file_dependents
Files that import from a given file
search_codebase
Regex search across all files (max 100 results)
reindex
Force full re-index (rarely needed — incremental updates happen automatically in git repos)
get_usage_stats
Session efficiency stats: tool calls, characters returned vs total source, estimated token savings
| Tool | Description |
|------|-------------|
| get_project_summary | File count, packages, top classes/functions |
| list_files | List indexed files with optional glob filter |
| get_structure_summary | Structure of a file or the whole project |
| get_functions | List functions with name, lines, params |
| get_classes | List classes with name, lines, methods, bases |
| get_imports | List imports with module, names, line |
| get_function_source | Full source of a function/method |
| get_class_source | Full source of a class |
| find_symbol | Find where a symbol is defined (file, line, type) |
| get_dependencies | What a symbol calls/uses |
| get_dependents | What calls/uses a symbol |
| get_change_impact | Direct + transitive dependents |
| get_call_chain | Shortest dependency path (BFS) |
| get_file_dependencies | Files imported by a given file |
| get_file_dependents | Files that import from a given file |
| search_codebase | Regex search across all files (max 100 results) |
| reindex | Force full re-index (rarely needed — incremental updates happen automatically in git repos) |
| get_usage_stats | Session efficiency stats: tool calls, characters returned vs total source, estimated token savings |
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp codebase index": {
"codebase-index": {
"command": "mcp-codebase-index",
"env": {
"PROJECT_ROOT": "/path/to/project"
}
}
}
}
}McpServers
{
"codebase-index": {
"command": "mcp-codebase-index",
"env": {
"PROJECT_ROOT": "/path/to/project"
}
}
}
[
]()
A structural codebase indexer with an MCP server for AI-assisted development. Zero runtime dependencies — uses Python's ast module for Python analysis and regex-based parsing for TypeScript/JS, Go, Rust, and C#. Requires Python 3.11+.
What It Does
Indexes codebases by parsing source files into structural metadata -- functions, classes, imports, dependency graphs, and cross-file call chains -- then exposes 18 query tools via the Model Context Protocol, enabling Claude Code and other MCP clients to navigate codebases efficiently without reading entire files.
Automatic incremental re-indexing: In git repositories, the index stays up to date automatically. Before every query, the server checks git diff and git status (~1-2ms). If files changed, only those files are re-parsed and the dependency graph is rebuilt. No need to manually call reindex after edits, branch switches, or pulls.
Persistent disk cache: The index is saved to a pickle cache file (.codebase-index-cache.pkl) after every build. On subsequent server starts, the cache is loaded and validated against the current git HEAD — if the ref matches, startup is instant. If a small number of files changed (≤20), the cached index is loaded and incrementally updated instead of rebuilt from scratch. This eliminates the cold-start penalty when restarting Claude Code sessions, restarting the MCP server, or resuming work after context compaction.
Language Support
| Language | Method | Extracts |
|----------|--------|----------|
| Python (.py) | AST parsing | Functions, classes, methods, imports, dependency graph |
| TypeScript/JS (.ts, .tsx, .js, .jsx) | Regex-based | Functions, arrow functions, classes, interfaces, type aliases, imports |
| Go (.go) | Regex-based | Functions, methods (receiver-based), structs, interfaces, type aliases, imports, doc comments |
| Rust (.rs) | Regex-based | Functions (pub/async/const/unsafe), structs, enums, traits, impl blocks, use statements, attributes, doc comments, macro_rules |
| C# (.cs) | Regex-based | Classes, interfaces, structs, enums, records, methods, constructors, using directives, [Attributes], /// XML doc comments |
| Markdown/Text (.md, .txt, .rst) | Heading detection | Sections (# headings, underlines, numbered, ALL-CAPS) |
| Other | Generic | Line counts only |
Installation
pip install "mcp-codebase-index[mcp]"
The [mcp] extra includes the MCP server dependency. Omit it if you only need the programmatic API.
For development (from a local clone):
pip install -e ".[dev,mcp]"
MCP Server
Running
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
