Code-Index-MCP Server

Code-Index-MCP is a local-first code indexer that runs alongside Claude Code and other AI assistants. It indexes your code locally for fast symbol search, cross-language support, and optional semantic search, while keeping your data private and readily available offline.

How to use

You use this MCP server by running it locally (stdio) or in a Docker container (http/remote options are also supported in some setups). Once the server is running, you connect your MCP client (such as Claude Code) to it to index your codebase, search for symbols, and perform code intelligence tasks. You can rebuild indexes, check status, and use semantic search if you enableVoyage AI.

How to install

Prerequisites: you should have Python 3.8+ or Docker installed depending on the method you choose.

Option A: Native Python (stdio) run using the Python command shown in the example configuration.

Option B: Docker (http/stdio) run using the Docker command shown in the example configuration.

Code and configuration samples

{
  "mcpServers": {
    "code-index-native": {
      "command": "python",
      "args": ["scripts/cli/mcp_server_cli.py"],
      "cwd": "${workspace}"
    }
  }
}

{
  "mcpServers": {
    "code-index-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspace}:/workspace",
        "ghcr.io/code-index-mcp/mcp-index:minimal"
      ]
    }
  }
}

Additional setup notes

Environment variables and runtime options may be required for semantic search or API integrations. You can place these in a .env file or export them in your shell before starting the MCP server.

Configuration and security

The server supports local-first operation with local index storage. You can enable semantic search with Voyage AI, and you can configure artifacts sharing and index synchronization to suit your privacy needs.

Troubleshooting and tips

If you run into issues connecting to the MCP server, verify that the command and arguments match the provided samples, ensure the working directory is correct, and confirm that required environment variables are set when semantic search is enabled.

Notes

Two common deployment options are native Python (stdio) and Docker (minimal image). The Python stdio approach runs the server locally, while Docker provides a portable container that isolates dependencies.

Developer workflow and tooling

If you are developing or extending the MCP server, use the provided CLI and dispatcher examples to index, rebuild, and expose endpoints for queries.

Available tools

index rebuild

Rebuilds the local code index from the repository contents.

index status

Checks the current status of the local index, including size and freshness.

artifact pull

Downloads the latest shared indexes from GitHub Artifacts.

artifact push

Pushes your local index to the configured artifact storage for team sharing.

hooks install

Installs git hooks to automate index synchronization on push/pull.