A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup
Code Index MCP is a specialized MCP server that provides intelligent code indexing and analysis capabilities. It enables Large Language Models to interact with your code repositories, offering real-time insights and navigation through complex codebases.
This server integrates with the Model Context Protocol (MCP), a standardized way for AI models to interact with external tools and data sources.
The server supports multiple programming languages and file extensions including:
There are several ways to set up and use Code Index MCP, depending on your needs.
This is the easiest and most common way to use the server. It's designed for users who want to use Code Index MCP within an AI application like Claude Desktop.
Prerequisite: Make sure you have Python 3.8+ and uv installed.
Configure the Host App: Add the following to your host application's MCP configuration file (e.g., claude_desktop_config.json
for Claude Desktop):
{
"mcpServers": {
"code-index": {
"command": "uvx",
"args": [
"code-index-mcp"
]
}
}
}
Restart the Host App: After adding the configuration, restart the application. The uvx
command will automatically handle the installation and execution of the code-index-mcp
server in the background.
If you want to contribute to the development of this project, follow these steps:
Clone the repository:
git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
Install dependencies using uv
:
uv sync
Configure Your Host App for Local Development: To make your host application (e.g., Claude Desktop) use your local source code, update its configuration file to execute the server via uv run
. This ensures any changes you make to the code are reflected immediately when the host app starts the server.
{
"mcpServers": {
"code-index": {
"command": "uv",
"args": [
"run",
"code_index_mcp"
]
}
}
}
Debug with the MCP Inspector: To debug your local server, you also need to tell the inspector to use uv run
.
npx @modelcontextprotocol/inspector uv run code_index_mcp
If you prefer to manage your Python packages manually with pip
, you can install the server directly.
Install the package:
pip install code-index-mcp
Configure the Host App: You will need to manually update your host application's MCP configuration to point to the installed script. Replace "command": "uvx"
with "command": "code-index-mcp"
.
{
"mcpServers": {
"code-index": {
"command": "code-index-mcp",
"args": []
}
}
}
Here’s a typical workflow for using Code Index MCP with an AI assistant like Claude.
This is the first and most important step. When you set the project path, the server automatically creates a file index for the first time or loads a previously cached one.
Example Prompt:
Please set the project path to C:\Users\username\projects\my-react-app
If you make significant changes to your project files after the initial setup, you can manually refresh the index to ensure all tools are working with the latest information.
Example Prompt:
I've just added a few new components, please refresh the project index.
(The assistant would use the refresh_index
tool)
Once the index is ready, you can find files using patterns (globs) to understand the codebase and locate relevant files.
Example Prompt:
Find all TypeScript component files in the 'src/components' directory.
(The assistant would use the find_files
tool with a pattern like src/components/**/*.tsx
)
Before diving into the full content of a file, you can get a quick summary of its structure, including functions, classes, and imports.
Example Prompt:
Can you give me a summary of the 'src/api/userService.ts' file?
(The assistant would use the get_file_summary
tool)
With an up-to-date index, you can search for code snippets, function names, or any text pattern to find where specific logic is implemented.
Example: Simple Search
Search for all occurrences of the "processData" function.
Example: Search with Fuzzy Matching
I'm looking for a function related to user authentication, it might be named 'authUser', 'authenticateUser', or something similar. Can you do a fuzzy search for 'authUser'?
Example: Search within Specific Files
Search for the string "API_ENDPOINT" only in Python files.
(The assistant would use the search_code
tool with the file_pattern
parameter set to *.py
)
git clone https://github.com/username/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code_index_mcp
You can use the MCP inspector to debug the server:
npx @modelcontextprotocol/inspector uvx code-index-mcp
Contributions are welcome! Please feel free to submit a Pull Request.
{ "mcpServers": { "code-index-mcp": { "command": "uvx", "args": [ "code-index-mcp" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories