home / mcp / code index mcp server

Code Index MCP Server

A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "johnhuang316-code-index-mcp": {
      "command": "uvx",
      "args": [
        "code-index-mcp"
      ],
      "env": {
        "HOME": "<your_home_path>",
        "APPDATA": "<your_appdata_path>",
        "SystemRoot": "<system_root>",
        "LOCALAPPDATA": "<your_localappdata_path>"
      }
    }
  }
}

Code Index MCP provides intelligent code indexing, advanced search, and deep code analysis to help AI assistants understand and navigate large codebases. It streams project context to your AI workflows, enabling fast code exploration, review, and debugging across multiple languages and file types.

How to use

Connect your MCP client to the Code Index MCP server and start indexing a local project. You can initialize a shallow index for quick file discovery and then build a deep symbol index for language-aware analysis. Use the server to set a project path, search across files, and request summaries of individual files to understand code structure, imports, and complexity.

Recommended workflow patterns you can run with your MCP client include: set the project path to your repository, find all TypeScript component files, search for authentication-related functions, and analyze the main entry file to grasp overall architecture.

How to install

Prerequisites: you need Python 3.10+ and uv ready in your environment.

1) Create or update your MCP configuration to include the Code Index server. You will run the MCP server locally through uvx.

2) Start the MCP server using the provided runtime command so it can index your project and serve analysis requests to your MCP client.

Code Index MCP server configurations

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

Windows-specific Codex CLI setup uses the same runtime but in a Windows-friendly TOML form. You can add the server to your Codex CLI configuration as shown here. Use the same command and arguments to start the server.

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

# Optional: environment overrides for Windows if you run inside a restricted container
env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Configuration notes and startup flow

Fast startup and discovery flow can be achieved with FastMCP by launching with the correct source entrypoint and including the repository path on startup. You can publish standard MCP manifests under ".well-known/mcp.json" and expose richer LLM feed metadata under ".well-known/mcp.llmfeed.json" to help clients present descriptions and capabilities automatically.

When you start the server, remember to provide the project path so the index boots against your intended repository. If you include a project path on startup, you can skip the initial project path setup step in prompts.

Typical use cases

Code Review: Find all places using the old API. Refactoring Help: Locate where a function is called. Learning Projects: Show the main components of a React project. Debugging: Search for error-handling patterns across the codebase.

Security and maintenance notes

Keep your environment variables and paths secure. Use only trusted project paths and avoid exposing your MCP endpoints to untrusted networks. Regularly refresh the index to reflect changes in your codebase and monitor the file watcher status to ensure the system remains up to date.

Troubleshooting

If automatic index updates aren’t working, ensure your runtime environment includes required tooling and try a manual refresh with the appropriate tool. Check the file watcher status to verify monitoring is active, and review any environment-specific constraints that may block indexing.

Development & contributing

To contribute or run locally, install dependencies, set up the local MCP server, and start the indexer. Use the appropriate inspector tool to debug and verify your MCP setup during development.

Available tools

set_project_path

Initialize indexing for a project directory

refresh_index

Rebuild the shallow file index after file changes

build_deep_index

Generate the full symbol index used by deep analysis

get_settings_info

View current project configuration and status

search_code_advanced

Smart search with regex, fuzzy matching, file filtering, and paginated results

find_files

Locate files using glob patterns

get_file_summary

Analyze file structure, functions, imports, and complexity

get_file_watcher_status

Check file watcher status and configuration

configure_file_watcher

Enable/disable auto-refresh and configure settings

create_temp_directory

Set up storage directory for index data

check_temp_directory

Verify index storage location and permissions

clear_settings

Reset all cached data and configurations

refresh_search_tools

Re-detect available search tools