claude-context: an MCP server that indexes a repository into a vector database for semantic code search

The problem claude-context targets: agents that grep their way to an answer

An agent asked to change a function signature has no index of the repository. It reads files, greps for symbols, reads more files, and repeats until it either finds the call sites or gives up and guesses. Each of those rounds costs tokens and latency, and the cost scales with repository size rather than with the size of the answer. claude-context attacks that loop directly. The README states the plugin "uses semantic search to find all relevant code from millions of lines" and that "no multi-round discovery needed" is the intended outcome. The audience is anyone running an MCP-capable coding agent against a codebase that does not fit comfortably in a context window: Claude Code first, but the README also documents configuration for OpenAI Codex CLI, Gemini CLI, Qwen Code, Cursor and Void. The second stated motivation is cost. Loading whole directories per request is described as expensive, so the plugin keeps the codebase in a vector database and pulls back only related code. That framing is honest about the trade: you pay for an index once so you stop paying for redundant reads on every turn.

How the index and the query path actually work

The architecture has three moving parts. A core library, published as @zilliz/claude-context-core, walks the repository, splits files into chunks, sends those chunks to an embedding model, and writes the resulting vectors into a Milvus-compatible store. An MCP server, published as @zilliz/claude-context-mcp, exposes search over that store as tools to the agent. The agent, not the index, decides when to search. The repository topics list merkle-tree alongside embedding and vector-database, which points at the incremental path: a Merkle tree over the file set lets the indexer detect which files changed since the last run and re-embed only those, rather than rebuilding from scratch. That is the difference between a usable tool on a large repository and an unusable one, because a full re-embed of a large tree on every session is both slow and billable. The README does not spell out the chunking strategy, the default embedding model, or the Merkle-tree invalidation rules, so those details have to be read out of the core package before you rely on them. What is clear from the configuration examples is that retrieval is exposed through MCP tools rather than injected automatically, which means the agent's own tool-selection behaviour determines whether you get the benefit.

Getting it running: the claude mcp add command and the three environment variables

The primary path is one command for Claude Code. The README gives this example: claude mcp add claude-context with -e OPENAI_API_KEY=sk-your-openai-api-key, -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint and -e MILVUS_TOKEN=your-zilliz-cloud-api-key, followed by -- npx @zilliz/claude-context-mcp@latest. Node.js 20 or later is required. The two external services are prerequisites, not options: an OpenAI API key for the embedding model, and a Milvus-compatible endpoint plus token, with the README pointing at Zilliz Cloud for a free tier. For other clients, the same three variables appear in different file formats. Codex CLI reads ~/.codex/config.toml and the README flags a trap explicitly: the top-level key is mcp_servers, not mcpServers, and there is a startup_timeout_ms field to override the default 10 second startup timeout, which the README sets to 20000 in its example. Gemini CLI and Qwen Code read ~/.gemini/settings.json and ~/.qwen/settings.json respectively, both using the mcpServers key. Cursor accepts a global ~/.cursor/mcp.json or a project-level .cursor/mcp.json. Note that some examples pass MILVUS_ADDRESS and some pass only MILVUS_TOKEN, so confirm which variables the current package reads before debugging a connection failure.

Where it breaks: credentials, ignore rules and a stale index

The first constraint is not technical. Indexing sends source code to the embedding provider named in your configuration, and the README's default is OpenAI. Any repository containing code that cannot leave the network is a poor fit for the default setup, and the README does not present a local embedding option. The second constraint is index freshness. A semantic index answers questions about the code as it was when the vectors were written. If the Merkle-tree diff misses a change (a rename that preserves content, a rebase, a branch switch), the agent receives confident results pointing at code that no longer exists, and it has no way to notice. Search quality is also bounded by chunking and by the embedding model, and neither is documented in the README, so a query that depends on cross-file reasoning may retrieve nothing useful. Third, the whole design assumes the agent chooses to call the search tool. A model that defaults to shelling out to grep will not benefit from an index it never queries. Finally, there is a real category of repository where this is the wrong tool: a small project that fits in context anyway, where the vector database and embedding round-trip add a dependency and a bill without removing any work.

Alternatives and the difference in approach

The obvious alternative is the retrieval already built into the editor. Cursor, for instance, ships its own codebase indexing and exposes it through the same MCP settings file that claude-context writes to. The difference is where the index lives and who controls it. An editor-native index is tied to that editor and its subscription; claude-context puts the vectors in a Milvus store you configure, so the same index can be queried from Claude Code, Codex CLI, Gemini CLI, Qwen Code and Cursor without re-indexing per client. That portability is the real argument for it, and it is a narrower argument than the README's framing suggests. The second alternative is doing nothing and letting the agent grep. For a mid-sized repository on a fast filesystem, ripgrep plus a competent model is often good enough, and it requires no API key, no vector database and no index to keep current. claude-context wins when the repository is large enough that grep returns too many candidates for the agent to sift, or when the same codebase is queried from several different agents and you want one index shared between them. It loses when the repository is small, when freshness cannot be guaranteed, or when the code is not permitted to leave the machine.

Maintenance cost, the MIT licence and what to check before committing

Two recurring costs sit outside the code. The embedding provider bills per indexing run, so the Merkle-tree incremental path is the mechanism that keeps that bill proportional to change rather than to repository size; if it does not fire correctly, cost scales with every session. The Milvus endpoint is a running service you own the availability of, and the README's quick start routes you to Zilliz Cloud, which makes the default deployment a hosted dependency rather than a local one. On the code side, the project is TypeScript, published to npm under two package names, with a companion VS Code extension (zilliz.semanticcodesearch) and a docs directory. The licence is MIT, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and if you redistribute a modified build you should read the MIT terms and any third-party embedding or database terms yourself. The repository shows no retrieved releases, so pinning @zilliz/claude-context-mcp@latest as the README does means accepting whatever ships next. Pinning an explicit version in your MCP configuration is the safer default for a tool that sits between your source tree and an external API.

Editorial conclusion

Adopt claude-context if your agent sessions routinely stall on multi-round file discovery in a repository too large to paste into context, and if you are willing to run a Milvus-compatible vector database plus pay an embedding provider per indexing run. Do not adopt it for a small repository, for a monorepo whose build artifacts are not covered by the default ignore rules, or for any environment where source code cannot leave the machine, because indexing sends file contents to the embedding API named in your MCP configuration. Before trusting it, verify three things from the repository itself: which environment variable names the current MCP package actually reads, what the ignore-file defaults exclude, and whether the Merkle-tree index invalidates correctly after a rebase.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. zilliztech/claude-context on GitHub