code-index-mcp, an MCP server that indexes the repository for the model

An index instead of a pile of file reads

code-index-mcp is a Model Context Protocol server that bridges AI models and complex codebases, and the value proposition is in the word index. An assistant that has only read access to a repository discovers a project by reading files one at a time, which is slow and incomplete, especially for the questions the README lists as typical use cases. Code review, where the question is where the old API is still used. Refactoring help, which is where a function is called from. Learning a project, which is what the main components of a React project are. Debugging, which is all the error handling code. For each of those, an index that already knows the symbols, the imports and the file structure answers directly. The audience is a developer who runs an MCP compatible assistant and wants it to be useful on a real repository rather than on toy examples, and the design constraint the README names is minimal setup, since the whole point is that you should not have to build a pipeline before you get value.

Install is one entry in your MCP configuration

The recommended setup assumes Python 3.10 or newer and uv, and the configuration is a single block in the JSON file your MCP client reads, for example claude_desktop_config.json or ~/.claude.json.

{
  "mcpServers": {
    "code-index": {
      "command": "uvx",
      "args": ["code-index-mcp"]
    }
  }
}

There is no separate install step because uvx handles both installation and execution, and the application is restarted afterwards so the client picks the server up. The optional --project-path argument is worth using, because it makes the server initialise against the right repository straight away, which is the same effect as calling the set_project_path tool after startup. The README then lists the prompts to give the assistant, starting with setting the project path, then finding all TypeScript files in the project, then searching for authentication functions, then analysing a specific main file. The order is not arbitrary, since the first prompt establishes the context the rest depend on.

Codex CLI, Windows paths and the discovery manifests

For Codex CLI the configuration is a TOML block in ~/.codex/config.toml, which on Windows lives at C:\Users\<you>\.codex\config.toml.

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

Windows has one extra wrinkle, and the README explains it plainly. uvx needs the standard profile directories to be present, so the configuration needs an environment override in the same block.

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux and macOS already expose the required XDG paths and HOME, so the env table can be omitted there, and the README says to add overrides only when running inside a restricted container. There is also a manifest route for clients that would rather import a file than craft configuration. fastmcp run fastmcp.json launches the server through FastMCP with the correct source entrypoint and dependency metadata, and .well-known/mcp.json is a standards compliant manifest that clients supporting the convention can import directly, with .well-known/mcp.llmfeed.json carrying the richer LLM Feed metadata including documentation and source links.

Ten languages parsed properly, everything else indexed

The parsing strategy is a deliberate two tier design, and the README is explicit that it is a choice rather than a limitation. Ten languages have specialised tree-sitter strategies with full AST analysis: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig and Rust. Everything else, more than fifty file types, is handled by a fallback strategy that gives basic file indexing. The direct tree-sitter integration has no regex fallback for the specialised languages, and the project says it fails fast with clear errors, which is a better failure mode than a half parsed file. The same philosophy shows up in the dependency list, where the README states there are no fallback mechanisms and the tool fails fast with clear error messages. The file analysis tool goes further than names: after you run build_deep_index it reports structure, imports, classes, methods and complexity metrics, and search auto-detects the best available tool among ugrep, ripgrep, ag and grep rather than insisting on one.

Beyond the ten, the file type list is long

The fallback tier covers more than the programming languages, and the README walks through the categories. C and C++, Ruby and PHP and the other languages are covered there. Frontend work is covered, with Vue, React, Svelte, HTML, CSS and SCSS. The Java web and build category is the most detailed, naming JSP and tag files with the .jsp, .jspx, .jspf, .tag and .tagx extensions, Grails and GSP with .gsp, Gradle and Groovy build files, .properties files, and Protocol Buffers with .proto. Database material is covered too, with SQL variants, NoSQL documents, stored procedures and migrations. Documents and configuration are covered with Markdown, JSON, YAML and XML. For a repository that is mostly Java with a build system, that list decides whether the assistant sees symbols or only text, and the answer for those files is text, since only the ten listed languages get the AST treatment.

The watcher keeps a shallow index fresh, and a deep rebuild fills in the symbols

Index freshness is handled by a file watcher using native operating system file system monitoring, so it works the same way on each platform, and the watcher batches rapid changes to prevent excessive rebuilds. The distinction between the two index levels is the part that matters in practice. The shallow index refresh watches for file changes and keeps the file list current, and a deep rebuild is what you run when you need symbol metadata. That is a deliberate split, since a deep parse of every file in a large repository is expensive, while the file list is cheap to maintain and is what most questions about where things live need. On top of that there is persistent caching, so an index survives between runs and the second access is fast, plus smart filtering that excludes build directories and temporary files. The performance claims in the README are about the architecture rather than about numbers, with memory efficiency and large codebase handling named as design goals rather than benchmarked results.

Packaging, dependencies and a weekly release rhythm

The project is a Python package built with setuptools and a src layout, and the entry point is a console script named code-index-mcp that maps to code_index_mcp.server:main. The pyproject dependencies are the MCP SDK at 1.21.0 or later but below 2.0.0, watchdog for the file watcher, the tree-sitter packages that cover several of the specialised languages, pathspec for the file filtering, and msgpack for the on disk index format. The requirements.txt file is close to the same list but not identical, adding protobuf and libclang 16.0.0 while omitting msgpack, which is worth noticing if you build from the requirements file rather than the package metadata. The container image is built on python:3.11-slim with git installed, sets PYTHONPATH to the application and its src directory, and starts the server in stdio mode by default, which is the transport an MCP client speaks. The repository also carries a fastmcp.json, a run.py, translated READMEs for Japanese, Korean and Chinese, a Dockerfile, and directories for docs, tests and agent configuration. The release tags are v2.16.0 on 2026-04-24, v2.17.0 on 2026-05-05 and v2.17.1 on 2026-07-27, and the last push was on 2026-07-27. The licence is MIT.

Editorial conclusion

code-index-mcp fits a team that has an AI assistant doing code review or refactoring over a repository large enough that reading files one at a time is the bottleneck, and it fits anyone who wants the assistant to have symbol level knowledge of a codebase rather than guesses. It does not fit a project that is mostly a language outside the ten the tree-sitter path covers, because those files fall back to basic indexing with no symbol metadata, and it does not fit an environment where the assistant must not read the source at all. Verify three things first: that the languages in your repository are among the ten the specialised parser covers, that the search tool you want is on the machine, since the server auto-detects ugrep, ripgrep, ag or grep rather than shipping one, and which index depth you are relying on, since a shallow refresh keeps the file list current but symbol metadata only comes from a deep rebuild.

Frequently asked questions

Official sources

1. Issues
2. johnhuang316/code-index-mcp on GitHub
3. License: MIT
4. README
5. Releases