Code Index MCP

Code-Index-MCP

Give your AI coding assistant instant, precise search across your whole codebase — so it finds the exact code it needs in milliseconds instead of burning time and tokens reading whole files.

Code-Index-MCP is a fast, local-first search index for your code. It plugs into Claude Code and other AI assistants (through the Model Context Protocol, "MCP") and lets them look up any symbol or search any text in your repository almost instantly — without your code ever leaving your machine.

> New to Code-Index-MCP? Start with the [Getting Started Guide](docs/GETTING_STARTED.md). > > Status: v1.3.1 stable surface prepared — MCP tools (search_code, symbol_lookup) are the primary interface; a FastAPI admin gateway is available for diagnostics.

> Stable-surface prep status: This guide targets the repo-owned 1.3.1 > hardening release candidate. MCP STDIO remains the primary LLM surface and > FastAPI remains a secondary admin surface. A July 10, 2026 collision check > found no live index-it-mcp==1.3.1, so this guide uses source and local-wheel > proof instead of claiming that the prepared 1.3.1 surface is published.

Project Status

Version: 1.3.1 (repo-owned prepared surface; unpublished as of July 10, 2026) Python distribution: index-it-mcp Container image: ghcr.io/viperjuice/code-index-mcp Primary surface: MCP tools (search_code, symbol_lookup) via the STDIO runner when repository readiness is ready Secondary surface: FastAPI admin REST gateway for diagnostics and scripting — see "Admin REST Interface (secondary)" below Core features: local indexing, symbol/text search, registry-based language coverage; see [docs/SUPPORTMATRIX.md](docs/SUPPORTMATRIX.md) Optional features: semantic search (requires Voyage AI or a local vLLM endpoint), GitHub Artifacts index sync Performance: sub-100ms symbol lookup and sub-500ms search on indexed repos (benchmarked on this codebase; results vary by repo size and language mix) GA decision: see [docs/validation/ga-final-decision.md](docs/validation/ga-final-decision.md); the current product decision is ship GA, while install-surface claims remain bounded by [docs/status/public-package-identity.md](docs/status/public-package-identity.md). GA readiness contract: see [docs/validation/ga-readiness-checklist.md](docs/validation/ga-readiness-checklist.md) for the frozen release boundary, support-tier labels, evidence ownership, and rollback expectations that apply before dispatch. Release dispatch: the historical governance record names this boundary GADISP; the current workflow implements it as a separate publish mode restricted to protected main. Repository model: one server can serve many unrelated repositories, with one registered worktree per git common directory. Only the tracked/default branch is indexed automatically. Indexed MCP results are authoritative only when readiness is ready; unavailable indexes return index_unavailable with safe_fallback: "native_search".

MCP_CLIENT_SECRET is a local STDIO handshake guard for mcp-index stdio. The FastAPI gateway uses separate admin/debug bearer token authentication, and no remote MCP authorization is implemented while remote MCP transport remains deferred.

Why it exists

When an AI assistant works in a large codebase, it often reads big chunks of files just to find what it needs. That's slow, and every file it reads costs tokens (money). Code-Index-MCP builds a local index so the assistant can jump straight to the right function, class, or line — cutting token cost and making answers faster and more accurate.

Who it's for

Developers and teams using AI coding assistants on real, sizable codebases who want faster, cheaper, more accurate results — and who want their code to stay private, on their own machine.

What you get

• ⚡ Instant lookups — sub-100ms symbol lookup, sub-500ms search on indexed repos.
• 🔒 Local-first & private — indexing runs on your machine; your code isn't shipped to a cloud.
• 💸 Lower token cost — the assistant searches instead of reading whole files (see the charts below).
• 🧠 Semantic search (optional) — natural-language code search via embeddings.
• 🌐 Many languages, many repos — one server can index multiple repositories with mixed languages.
• 🔌 Plugin-based & extensible — add language support without touching the core.

See it in action

Benchmarks in this repository show large token/cost reductions when an assistant searches with Code-Index-MCP instead of reading files directly:

(Charts generated from the benchmarks in reports/; numbers vary by repo size and language mix.)

🎯 Key Features

• 🚀 Local-First Architecture: All indexing happens locally for speed and privacy
• 📂 Local Index Storage: All indexes stored at .indexes/ (relative to MCP server)
• 🔌 Plugin-Based Design: Easily extensible with language-specific plugins
• 🔍 Language support: Tiered language/runtime support is documented in [docs/SUPPORTMATRIX.md](docs/SUPPORTMATRIX.md)
• ⚡ Real-Time Updates: File system monitoring for instant index updates
• 🧠 Semantic Search: AI-powered code search with Voyage AI embeddings
• 📊 Rich Code Intelligence: Symbol resolution, type inference, dependency tracking
• 🚀 Enhanced Performance: Sub-100ms queries with timeout protection and BM25 bypass
• 🔄 Git Synchronization: Automatic index updates tracking repository changes
• 📦 Portable Index Management: Zero-cost index sharing via GitHub Artifacts
• 🔄 Automatic Index Sync: Pull indexes on clone, push on changes
• 🎯 Smart Result Reranking: Multi-strategy reranking for improved relevance
• 🎯 Query-Intent Routing: Symbol-pattern queries (class Foo, def bar, CamelCase) bypass BM25 and hit the symbols table directly for sub-5ms lookups
• 🔒 Security-Aware Export: Automatic filtering of sensitive files from shared indexes
• 🔍 Hybrid Search: BM25 + semantic search with configurable fusion
• 🔐 Index Everything Locally: Search .env files and secrets on your machine
• 🚫 Smart Filtering on Share: .gitignore and .mcp-index-ignore patterns applied only during export
• 🌐 Multi-Language Indexing: Index entire repositories with mixed languages

🏗️ Architecture

The Code-Index-MCP follows a modular, plugin-based architecture designed for extensibility and performance:

System Layers

1. 🌐 System Context (Level 1)

• Developer interacts with Claude Code or other LLMs
• MCP protocol provides standardized tool interface
• Local-first processing with optional cloud features
• Performance SLAs: (registered name or path) to searchcode / symbollookup`:

search_code(query="def parse", repository="my-repo")
symbol_lookup(symbol="Parser", repository="my-repo")

Python client (beta local API): for local scripts and applications on the same machine as the registered repo, use mcp_server.client instead of starting STDIO or calling FastAPI. MCP tools remain the preferred LLM surface.

from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root="/path/to/repo") as client:
    result = client.search_code(
        ClientSearchOptions(
            query="TODO",
            source_type="friction",
            friction_categories=("todo",),
            include_source_metadata=True,
        )
    )
    if result.index_unavailable:
        print(result.index_unavailable.safe_fallback)
    else:
        print(result.results[0].file)

The supported Python client surface is local-only: search_code, symbol_lookup, reindex, and get_status share the same readiness-aware service as the MCP search_code tool. It is a local programmatic API, not a remote service client.

Friction pattern metadata is available as an additive filter on search_code. Use source_type="friction" with optional friction_categories=["todo", "fixme", "hack", "workaround", "wish", "extraction_hint"]. Set include_source_metadata=true to attach the stored search_source_metadata.v1 envelope to returned results. Ordinary unfiltered lexical calls keep the legacy result shape; invalid friction categories return a metadata-only validation error instead of a silent empty result.

Historical GitHub issue context uses the same metadata envelope and search surface. Run mcp-index history ingest --repo owner/repo to ingest metadata-only issue documents, then filter them with source_type="history" plus optional history_labels=["reflection"] or history_repos=["owner/repo"]. The HISTORY contract is fixture-backed in tests, requires no live GitHub credentials, and does not persist raw issue bodies by default.

Index tracking: each repo's tracked/default branch is followed by MultiRepositoryWatcher (RefPoller every 30 s). Same-repo multiple worktrees and non-default branch queries are unsupported in v3 routing: they return index_unavailable with safe_fallback: "native_search" and readiness remediation instead of reusing another checkout's index. Check get_status or mcp-index repository list -v and trust indexed MCP results only when readiness is ready.

Path sandbox: tools search_code, symbol_lookup, summarize_sample, and reindex reject paths outside MCP_ALLOWED_ROOTS with error code path_outside_allowed_roots. Registered repo names bypass the check.

Options:

• Set MCP_AUTO_INDEX=false in the server environment to skip background auto-indexing and call the reindex MCP tool manually (recommended for very large repos).
• Add {"enabled": false} to .mcp-index.json in the target repo to disable indexing for that repo entirely.
• After a full reindex or code changes, call the reindex MCP tool to rebuild the index on demand.

Semantic profiles: BM25 search requires no extra config. For semantic (vector) search, the server automatically loads code-index-mcp.profiles.yaml from its own installation directory — no need to copy it to each repo. To override with a custom profile file, set MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml in the server environment. To override individual endpoint URLs without editing the YAML, use the env vars referenced in the file (e.g. VLLM_EMBEDDING_BASE_URL, VLLM_SUMMARIZATION_BASE_URL).

⚡ Enable Semantic Search

BM25 keyword search works with zero configuration. To add vector (semantic) search, choose one path:

Option A — Voyage AI (recommended):

export VOYAGE_API_KEY=your-key   # free tier available at voyageai.com

The commercial_high profile activates automatically. Restart the MCP server — the startup log will confirm semantic search is active.

Option B — Local OSS (Qwen3-Embedding-8B via vLLM, no API key needed):

export VLLM_EMBEDDING_BASE_URL=http://localhost:8000/v1
# Start vLLM (requires ~20GB VRAM or shared CPU with --dtype float32):
docker run -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen3-Embedding-8B

Both profiles and their collection names are defined in code-index-mcp.profiles.yaml and can be customized.

code-index-mcp.profiles.yaml is a repo-shipped profile filename, not a pip install target.

Costs & Optional Features

The documented container package is ghcr.io/viperjuice/code-index-mcp. BM25 code search works without provider credentials. Semantic search, reranking, artifact sync, and monitoring depend on extras, environment variables, and service configuration. See [docs/SUPPORTMATRIX.md](docs/SUPPORTMATRIX.md) for language/runtime support details.

🚀 Quickstart (Python)

Prerequisites

• Python 3.12+
• Git

Installation

Option 1: Use the repo-owned source install (Recommended)

# Clone the repository
git clone https://github.com/ViperJuice/Code-Index-MCP.git
cd Code-Index-MCP

# Install locked project dependencies
uv sync --locked

# Verify the canonical CLI entrypoint
uv run mcp-index --version

Option 2: Build the local wheel

# From the repo root
uv run --extra dev python -m build --wheel
python -m pip install dist/index_it_mcp-1.3.1-py3-none-any.whl
index-it-mcp --version

The canonical Python distribution name remains index-it-mcp, but the live PyPI currently has no published artifact for this repo's prepared 1.3.1 surface. Use the local wheel or source install above until a later release-evidence phase re-proves live package parity.

Quick Start After Installation

# Authenticate GitHub artifact access once
gh auth login

# Check repo/artifact readiness before starting work
mcp-index preflight

# Pull the latest published index baseline for this repo
mcp-index artifact pull --latest

# Reconcile only your local drift after restore
mcp-index artifact sync

# The restored files live locally for MCP runtime use:
# - code_index.db
# - .index_metadata.json
# - vector_index.qdrant/

# Check index status
mcp-index index status

# Start the MCP STDIO runner (primary surface used by LLMs via .mcp.json)
mcp-index stdio

# Or start the FastAPI admin REST gateway (secondary, for diagnostics only;
# this is not the repo's MCP Streamable HTTP transport)
mcp-index serve
mcp-index serve --port 9123   # alternate port

From an LLM (Claude Code, Cursor, …) register the STDIO runner in .mcp.json and invoke the indexer as MCP tool calls. The two primary tools are search_code (pattern / keyword / semantic search, :8001/v1`

• SSH Tunnel: Run ssh -L 8001:localhost:8001 user@remote-gpu-machine, and the default 127.0.0.1:8001 configuration will tunnel directly to your inference server.

The generated index files are not meant to live in git history. The repo tracks the code, workflow, and configuration needed to build/publish them; GitHub artifacts distribute the actual runtime baseline that MCP restores locally.

Local Workspace Management

# Inspect all registered repositories and their readiness
mcp-index repository list -v

# Check all registered repos and their local artifact/runtime readiness
mcp-index artifact workspace-status

# Refresh readiness after restoring or rebuilding local indexes
mcp-index artifact reconcile-workspace

# Prepare per-repo local artifact payloads without requiring remote publication
mcp-index artifact publish-workspace

MRREADY freezes the rollout-facing interpretation of those commands:

• mcp-index repository list -v, mcp-index repository status, and

mcp-index artifact workspace-status now surface one rollout status per repository: ready, local_only, publish_failed, wrong_branch, stale_commit, missing_index, or partial_index_failure.

• Query tools remain a separate fail-closed surface. If readiness is not

ready, MCP search returns index_unavailable with safe_fallback: "native_search" instead of treating a status row as a query success.

• The current multi-repo verdict remains controlled rollout only while the

multi-repo and STDIO surfaces are still beta.

🔐 Privacy & GitHub Artifact Sync

Control how your code index is shared:

// .mcp-index.json
{
  "github_artifacts": {
    "enabled": false,        // Disable sync entirely
    "auto_upload": false,    // Manual upload only
    "auto_download": true,   // Still get team indexes
    "exclude_patterns": [    // Additional exclusions
      "internal/*",
      "proprietary/*"
    ]
  }
}

Privacy Features:

• Indexes filtered by .gitignore automatically
• Additional patterns via .mcp-index-ignore
• Audit logs show what was excluded
• Sync disabled by default in Docker minimal version

🆕 Advanced Features

Search Result Reranking

Three rerankers are available, configured via the RERANKER_TYPE environment variable:

| Value | Reranker | Notes | |---|---|---| | flashrank | FlashRank | OSS, local, fast (~1–5 ms overhead) | |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Consiliency
• Source: Consiliency/Code-Index-MCP
• License: MIT

Install and usage instructions live in the source repository linked above.