Guide · Open source

How to use claude-context: semantic code search for Claude Code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

claude-context is an open-source MCP plugin that adds semantic code search to Claude Code and other AI coding agents. It indexes your codebase into a vector database so the agent can find relevant code by meaning and load only that code into its context. This guide walks through the accounts you need, the install command, and configuration for other MCP clients so you can get it running.

claude-contextzilliztech/claude-context · ★ 12.7k · MIT Install options & downloads

Quick start

1Create a Zilliz Cloud account. Sign up on Zilliz Cloud and copy your Personal Key and public endpoint. You will use them as MILVUS_TOKEN and MILVUS_ADDRESS.
2Get an OpenAI API key. Create a key at the OpenAI API keys page. It starts with sk-.
3Check Node.js. Make sure Node.js 20.0.0 or newer is installed.
4Add the MCP server to Claude Code. Run the claude mcp add command with your three values in place of the placeholders.
5Configure other clients if needed. For Cursor, Gemini CLI, Codex CLI or another client, add the matching JSON or TOML block and restart the app.

What you need before you install claude-context

You need Node.js 20 or newer. You also need an OpenAI API key for the embedding model, which the README says always starts with sk-. Finally, you need a Zilliz Cloud account, because claude-context needs a vector database and the README points to Zilliz Cloud for this.

Node.js 20.0.0 or newer
An OpenAI API key (starts with sk-)
A Zilliz Cloud account, with your Personal Key and public endpoint

Add the claude-context MCP server to Claude Code

Use the Claude Code command line to register the server. Replace the three placeholder values with your own OpenAI key, Zilliz Cloud public endpoint and Zilliz Cloud API key. The command runs the MCP package through npx, using the latest tag.

The README links to the Claude Code MCP documentation for more on managing MCP servers.

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -- npx @zilliz/claude-context-mcp@latest

Configure claude-context in other MCP clients

The README has separate instructions for several clients, including OpenAI Codex CLI, Gemini CLI, Qwen Code, Cursor, Void, Claude Desktop, Windsurf and VS Code. Most use a JSON file with a mcpServers block that sets the same environment variables.

Codex CLI is different: it uses a TOML file at ~/.codex/config.toml, and the top-level key is mcp_servers rather than mcpServers. Codex also omits MILVUS_ADDRESS in the example, so check the README for your client before copying.

Codex CLI: edit ~/.codex/config.toml and restart the CLI
Gemini CLI: edit ~/.gemini/settings.json and restart the CLI
Cursor: paste into ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)
Claude Desktop, Windsurf, VS Code: add the JSON block to each app's MCP settings

Understand what claude-context does with your code

According to the project, claude-context stores your codebase in a vector database and uses semantic search to find relevant code. The agent then brings only those results into its context, rather than loading entire directories on every request. The README says this is meant to keep costs manageable on large codebases.

Because embeddings are created with OpenAI and the index lives in Zilliz Cloud, your code is sent to those third-party services. Factor that in before you use it on private code.

Troubleshooting and documentation

The README does not include a troubleshooting section in the portion provided. For detailed usage, the project lists a docs folder in its homepage link, and the README mentions DeepWiki and a Discord community. If a client does not start, the Codex example shows an optional startup_timeout_ms setting, with a 10 second default.

Check that all three environment variables are set for your client
Confirm Node.js is version 20 or newer
Use the project docs folder and Discord for further help

What people use it for

Searching a large codebase by meaning rather than exact file names
Giving Claude Code relevant code without loading whole directories each request
Using the same MCP server from Cursor, Gemini CLI or Codex CLI
Reducing context costs on big projects, as the README describes

Frequently asked questions

Is claude-context free to use?

The project is released under the MIT licence. The README does not state prices for OpenAI or Zilliz Cloud, so check those services directly to see what your usage will cost.

What do I need to install claude-context?

You need Node.js 20 or newer, an OpenAI API key for embeddings, and a Zilliz Cloud account with a public endpoint and token. The install is a single claude mcp add command for Claude Code.

Can I run claude-context fully local?

The README describes OpenAI embeddings and a Zilliz Cloud vector database. It does not describe a local option, so it is not a fit if you need everything kept on your own machine.

Which AI coding tools does claude-context work with?

The README lists Claude Code, OpenAI Codex CLI, Gemini CLI, Qwen Code, Cursor, Void, Claude Desktop, Windsurf, VS Code and Cherry Studio. It describes these as MCP-compatible clients.

What are the alternatives to claude-context?

The source lists Sourcegraph Cody, Continue and Aider as comparable projects. The README does not compare them directly, so test each against your own codebase.

Where do I find the API key values?

The README says to copy your Zilliz Cloud Personal Key to replace your-zilliz-cloud-api-key, and to copy your OpenAI key, which starts with sk-, into the configuration examples.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

claude-context suits developers on large codebases who already use Claude Code or another MCP-compatible agent, and who are comfortable creating OpenAI and Zilliz Cloud accounts. If you need a fully local setup, or your project is small enough for the agent to read directly, or you cannot send code embeddings to third-party services, pick a different tool such as Aider or Continue.

Install options & downloads