Code Index MCP
An MCP server that indexes a local repository with tree-sitter and gives the agent code search, file lookup and a structure summary of a file
- 1,007 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads and indexes every file in the chosen project, including configuration and keys that sit in the folder
- Stores the index and settings in a service folder on disk and keeps a background file watcher running
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/johnhuang316-code-index-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads and indexes every file in the chosen project, including configuration and keys that sit in the folder
- Stores the index and settings in a service folder on disk and keeps a background file watcher running
This is third-party code. Review the repository files before installing.
What it does
The server starts on your machine through `uvx code-index-mcp` and works with one project at a time: the agent calls `set_project_path` and the server builds a shallow index of the file list. Symbols need a deep index, which `build_deep_index` creates. Ten languages (Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig and Rust) are parsed by tree-sitter into classes, functions and calls, and fifty-plus other file types get basic indexing. `search_code_advanced` picks the installed tool among ugrep, ripgrep, ag and grep. By default it searches a literal string, and with `regex=True` a regular expression, which needs a native tool because the fallback understands literal search only. There is fuzzy matching, a file pattern filter and paging at ten results. `find_files` looks files up by glob pattern, and `get_file_summary` shows functions, imports and complexity of a file after a deep index. The index lives in storage that the server prepares with `create_temp_directory`. A file watcher built on watchdog updates the list on changes and batches frequent edits into one rebuild. The `configure_file_watcher` tool turns it on and off and changes the delay.
Who it is for. For developers who work on a large codebase through Claude Code, Codex or another MCP client and want the agent to search an index instead of walking directories.
Good fit when
- A project has hundreds of files and the agent spends requests walking directories: `find_files` with a pattern like `**/*.py` finds what it needs in one call
- You need every call of a deprecated method: `search_code_advanced` searches by name, regular expression or fuzzy match
- You want a quick summary of a file such as `src/api/userService.ts`: `get_file_summary` shows functions, imports and complexity
- The project is Java, Kotlin, C#, Go, Rust or Zig, where classes and methods matter: each has a dedicated tree-sitter parser
- The index should refresh itself as the agent edits: turn on the file watcher
Not a fit when
- You need symbol-level edits and renames through a language server: Serena does that, while Code Index MCP only reads and searches
- You want individual functions and classes returned by full name with an import graph: jcodemunch-mcp fits that work
- The machine has no Python 3.10 and no uv manager, and you cannot install them
- The project is C, C++, Ruby, PHP or Swift and you need symbols: those languages go through the fallback parser and get basic indexing without symbols
Example request
Set the project path to /Users/dev/my-react-app, build the deep index and find every place that calls the old getUserData methodMCP
- Transport
- stdio
- Authentication
- not required
Limitations
- A file summary and symbols are available only after `build_deep_index`. Without it the server answers `needs_deep_index`, and the shallow index holds only the file list.
- Regular expressions work when ugrep, ripgrep or ag is installed. The fallback search understands a literal string only.
- Auto refresh runs through watchdog. When it does not fire, `pip install watchdog` or a manual `refresh_index` call helps. On macOS the watcher can switch from FSEvents to kqueue or polling; kqueue opens one descriptor per file, so large projects may need `ulimit -n 10240`.
- On Windows for Codex the `env` block needs `HOME`, `APPDATA`, `LOCALAPPDATA` and `SystemRoot`, or `uvx` may fail to start.
- The server holds the index of one project at a time. For another repository call `set_project_path` again or start the server with `--project-path`.
How to disable. Remove the `code-index` block from `mcpServers` in `claude_desktop_config.json` or `~/.claude.json`, and for Codex delete the `[mcp_servers.code-index]` section from `~/.codex/config.toml`. The `clear_settings` tool resets the saved index. A pip install is removed with `pip uninstall code-index-mcp`.
FAQ
What is the difference between the shallow and the deep index?
The shallow index stores the file list and is built on `set_project_path` and `refresh_index`. The deep index with symbols is built by `build_deep_index` and is needed for `get_file_summary`. The file watcher updates only the shallow index, and symbols are rebuilt by calling the tool again.
How do I turn on regular expressions?
Pass `regex=True` to `search_code_advanced` and install ugrep, ripgrep or ag. Without a native tool the fallback search handles only a literal string. `refresh_search_tools` re-detects the available tools.
Which languages get deep parsing?
Ten: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig and Rust. Other languages, web files, SQL, Markdown and configuration files are indexed at a basic level through the fallback parser.
How do I set the project at startup?
Append `--project-path /absolute/path/to/repository` to the `args` array in the configuration. The server then initializes the project on start and you do not need to call `set_project_path`.
What if the server does not see new files?
Check `get_file_watcher_status`. If the watcher is not running, install `watchdog` or call `refresh_index` after edits. `configure_file_watcher` changes the watcher settings.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server that indexes code with tree-sitter and returns individual functions and classes to the agent instead of whole files
An MCP server and CLI for code research: search and understand your project and all of GitHub with fewer tokens
A local codebase index for agents: hybrid search, dependency graphs and change impact analysis
An MCP server that lets an agent read files, search code and run commands in a workspace
An MCP server that builds a code graph of functions, classes, calls and routes and answers the agent's structural queries locally
A local MCP server that indexes your code so the agent pulls the functions it needs instead of rereading whole files
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Code Index MCP (this entry) | no | not required | 1,007 | |
| Serena | no | not required | 30,849 | gives the agent symbol-level edits through language servers; Code Index MCP reads and searches an index |
| jCodeMunch MCP | no | not required | 2,817 | returns individual functions and classes by full name, over 70 languages; Code Index MCP focuses on search and file summaries |
README in short
The documentation covers a quick start through `uvx` for Claude Desktop and Codex, the tools grouped by purpose, sample requests to the agent and a list of supported files. Separate sections cover the file watcher, macOS troubleshooting and building from source. The repository holds `.well-known/mcp.json` and `fastmcp.json` manifests, a Dockerfile, Python sources with indexing and search packages, two notes in `docs` and documentation translations into Chinese, Japanese and Korean.