Code-Index-MCP
About
A local-first code indexer that enhances LLMs with deep code understanding. It integrates with AI assistants via the Model Context Protocol (MCP) and supports AI-powered semantic search.
Explore
- Local-first architecture for speed and privacy
- Plugin-based design for extensibility
- Multi-language support (Python, C/C++, JavaScript, Dart, HTML/CSS)
- Real-time file system monitoring for instant index updates
- AI-powered semantic search with Voyage AI embeddings
- Rich code intelligence: symbol resolution, type inference, dependency tracking
# Auto-configures MCP for your environment ./scripts/setup-mcp-json.sh # Or interactive mode ./scripts/setup-mcp-json.sh --interactive
This automatically detects your environment and creates the appropriate.mcp.jsonconfiguration.
Pull the publishedv1.4.0image from GHCR. The installer defaults to this published image; thelocal-smoketag remains an optional dev image you can build from this checkout withmake release-smoke-container.
# 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
# From the repo root uv run --extra dev python -m build --wheel python -m pip install dist/index_it_mcp-1.4.0-py3-none-any.whl index-it-mcp --version
The canonical Python distribution name remainsindex-it-mcp, but the live PyPI currently has no published artifact for this repo's prepared1.4.0surface. Use the local wheel or source install above until a later release-evidence phase re-proves live package parity.
# 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.jsonand invoke the indexer as MCP tool calls. The two primary tools aresearch_code(pattern / keyword / semantic search, <500 ms) andsymbol_lookup(exact class/function lookup, <100 ms). Callget_statusto confirm repository readiness isready, or handle a query response withcode: "index_unavailable"andsafe_fallback: "native_search"by using native search while following the returned remediation, such asreindex:
{ "tool": "search_code", "arguments": { "query": "def parse", "limit": 20, "semantic": false } }
{ "tool": "symbol_lookup", "arguments": { "symbol": "parse_file" } }
Both tools accept an optional"repository"argument (registered repo name or an absolute path insideMCP_ALLOWED_ROOTS) for multi-repo scoping. See the "Using Against Many Repos" section above. A ready index with no matches returns ordinary no-match payloads (results: ](https://github.com/ViperJuice/Code-Index-MCP/blob/HEAD/docs/SUPPORT_MATRIX.md)[]forsearch_codeorresult: "not_found"forsymbol_lookup) with readiness metadata; unavailable indexes returnindex_unavailableinstead.
The STDIOtools/listsurface is deterministic and now advertises richer MCP metadata for every public tool: stabletitlevalues, explicit JSON Schema input contracts (required, defaults, andadditionalPropertiesposture), annotations for read-only versus mutating behavior, and implementation-ownedoutputSchemadrafts. The STDIOtools/callsurface now returns SDK-nativeCallToolResultobjects with object-shapedstructuredContent, preserved JSON text fallback content incontentfor older clients, andisErroron refusal and error branches. Legacy array-like payloads such as plain lexical search hits are wrapped understructuredContent.results, while readiness failures still carryindex_unavailablewithsafe_fallback: "native_search"where that contract already applied.
reindexandwrite_summariesalso support task-augmented execution through the SDK-native MCP tasks surface. Both tools advertiseexecution.taskSupport = "optional", so clients can either keep the current synchronous path or include ataskobject intools/calland then usetasks/get,tasks/list,tasks/result, andtasks/cancelfor progress, terminal payload retrieval, and best-effort cancellation. Readiness refusals, path sandbox failures, conflicting scope errors, and summarizer-unavailable preflights still fail synchronously before any task is created.
Current verified MCP client posture is summarized in theMCP compatibility matrix. The phase-owned direct smoke is the official Python SDK over STDIO; Claude Code and other STDIO launchers are documented against that same server contract, while remote Streamable HTTP MCP remains deferred.
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-firstsearch 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 theGetting Started Guide.
Status:v1.4.0 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-owned1.4.0hardening release candidate. MCP STDIO remains the primary LLM surface and FastAPI remains a secondary admin surface. A July 10, 2026 collision check found no liveindex-it-mcp==1.4.0, so this guide uses source and local-wheel proof instead of claiming that the prepared1.4.0surface is published.
Version: 1.4.0 (repo-owned prepared surface; unpublished as of July 10, 2026)Python distribution:index-it-mcpContainer image:ghcr.io/consiliency/code-index-mcpPrimary surface: MCP tools (search_code,symbol_lookup) via the STDIO runner when repository readiness isreadySecondary surface: FastAPI admin REST gateway for diagnostics and scripting — see "Admin REST Interface (secondary)" belowCore features: local indexing, symbol/text search, registry-based language coverage; seedocs/SUPPORT_MATRIX.mdOptional features: semantic search (requires Voyage AI or a local vLLM endpoint), GitHub Artifacts index syncPerformance: 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: seedocs/validation/ga-final-decision.md; the current product decision isship GA, while install-surface claims remain bounded bydocs/status/public-package-identity.md.GA readiness contract: seedocs/validation/ga-readiness-checklist.mdfor the frozen release boundary, support-tier labels, evidence ownership, and rollback expectations that apply before dispatch.Release dispatch: the historical governance record names this boundaryGADISP; the current workflow implements it as a separatepublishmode restricted to protectedmain.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 isready; unavailable indexes returnindex_unavailablewithsafe_fallback: "native_search".
MCP_CLIENT_SECRETis a local STDIO handshake guard formcp-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.
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.
Developers and teams using AI coding assistants on real, sizable codebases who wantfaster, cheaper, more accurateresults — and who want their code to stayprivate, on their own machine.
- ⚡ 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 assistantsearchesinstead 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.
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 inreports/; numbers vary by repo size and language mix.)
- 🚀 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/SUPPORT_MATRIX.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
The Code-Index-MCP follows a modular, plugin-based architecture designed for extensibility and performance:
- Developer interacts with Claude Code or other LLMs
- MCP protocol provides standardized tool interface
- Local-first processing with optional cloud features
- Performance SLAs: <100ms symbol lookup, <500ms search
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ API Gateway │────▶│ Dispatcher │────▶│ Plugins │ │ (FastAPI) │ │ │ │ (Language) │ └─────────────────┘ └──────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ Local Index │ │ File Watcher │ │ Embedding │ │ (SQLite+FTS5) │ │ (Watchdog) │ │ Service │ └─────────────────┘ └──────────────┘ └─────────────┘
- Gateway Controller: RESTful API endpoints
- Dispatcher Core: Plugin routing and lifecycle
- Plugin Base: Standard interface for all plugins
- Language Plugins: Specialized parsers and analyzers
- Index Manager: SQLite with FTS5 for fast searches
- Watcher Service: Real-time file monitoring
Code-Index-MCP implements defense-in-depth security hardening (Phase 15):
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
