🚀 Claude Context
Claude Context is an MCP plugin that adds semantic code search to Claude Code and other AI coding agents, enabling them to access deep context from your entire codebase. It uses semantic search to find relevant code efficiently and is cost - effective for large codebases.
Key Features
🧠 Your Entire Codebase as Context: Find all relevant code from millions of lines with semantic search, bringing results directly into Claude's context without multi - round discovery.
💰 Cost - Effective for Large Codebases: Efficiently store your codebase in a vector database and use only related code in context to control costs, instead of loading entire directories for each request.
Badges
🚀 Demo
The Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, such as Claude Code.
🚀 Quick Start
Prerequisites
Get a free vector database on Zilliz Cloud 👈
Claude Context requires a vector database. You can sign up on Zilliz Cloud to obtain an API key.
Copy your Personal Key to replace your-zilliz-cloud-api-key in the configuration examples.
Get OpenAI API Key for embedding model
You need an OpenAI API key for the embedding model. You can get one by signing up at OpenAI.
Your API key will start with sk-.
Copy your key and use it in the configuration examples below as your-openai-api-key.
Configure MCP for Claude Code
System Requirements:
- Node.js >= 20.0.0 and < 24.0.0
⚠️ Important Note:
Claude Context is not compatible with Node.js 24.0.0. If your node version is greater than or equal to 24, you need to downgrade it first.
Configuration
Use the command - line interface to add the Claude Context MCP server:
claude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-openai-api-key \
-e MILVUS_TOKEN=your-zilliz-cloud-api-key \
-- npx @zilliz/claude-context-mcp@latest
See the Claude Code MCP documentation for more details about MCP server management.
Other MCP Client Configurations
OpenAI Codex CLI
Codex CLI uses TOML configuration files:
- Create or edit the
~/.codex/config.toml file.
- Add the following configuration:
[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }
startup_timeout_ms = 20000
- Save the file and restart Codex CLI to apply the changes.
Gemini CLI
Gemini CLI requires manual configuration through a JSON file:
- Create or edit the
~/.gemini/settings.json file.
- Add the following configuration:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
- Save the file and restart Gemini CLI to apply the changes.
Qwen Code
Create or edit the ~/.qwen/settings.json file and add the following configuration:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
Cursor
Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
It is recommended to paste the following configuration into your Cursor ~/.cursor/mcp.json file. You can also install it in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more information.
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
Void
Go to: Settings -> MCP -> Add MCP Server
Add the following configuration to your Void MCP settings:
{
"mcpServers": {
"code-context": {
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
Claude Desktop
Add to your Claude Desktop configuration:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
Windsurf
Windsurf supports MCP configuration through a JSON file. Add the following configuration to your Windsurf MCP settings:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
VS Code
The Claude Context MCP server can be used with VS Code through MCP - compatible extensions. Add the following configuration to your VS Code MCP settings:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
Cherry Studio
Cherry Studio allows for visual MCP server configuration through its settings interface. While it doesn't directly support manual JSON configuration, you can add a new server via the GUI:
- Navigate to Settings → MCP Servers → Add Server.
- Fill in the server details:
- Name:
claude-context
- Type:
STDIO
- Command:
npx
- Arguments:
["@zilliz/claude-context-mcp@latest"]
- Environment Variables:
OPENAI_API_KEY: your-openai-api-keyMILVUS_ADDRESS: your-zilliz-cloud-public-endpointMILVUS_TOKEN: your-zilliz-cloud-api-key
- Save the configuration to activate the server.
Cline
Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration:
- Open Cline and click on the MCP Servers icon in the top navigation bar.
- Select the Installed tab, then click Advanced MCP Settings.
- In the
cline_mcp_settings.json file, add the following configuration:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
- Save the file.
Augment
To configure Claude Context MCP in Augment Code, you can use either the graphical interface or manual configuration.
A. Using the Augment Code UI
- Click the hamburger menu.
- Select Settings.
- Navigate to the Tools section.
- Click the + Add MCP button.
- Enter the following command:
npx @zilliz/claude-context-mcp@latest
- Name the MCP: Claude Context.
- Click the Add button.
B. Manual Configuration
- Press Cmd/Ctrl + Shift + P or go to the hamburger menu in the Augment panel.
- Select Edit Settings.
- Under Advanced, click Edit in settings.json.
- Add the server configuration to the
mcpServers array in the augment.advanced object.
"augment.advanced": {
"mcpServers": [
{
"name": "claude-context",
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
]
}
Roo Code
Roo Code utilizes a JSON configuration file for MCP servers:
- Open Roo Code and navigate to Settings → MCP Servers → Edit Global Config.
- In the
mcp_settings.json file, add the following configuration:
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
- Save the file to activate the server.
Zencoder
Zencoder offers support for MCP tools and servers in both its JetBrains and VS Code plugin versions.
- Go to the Zencoder menu (...).
- From the dropdown menu, select
Tools.
- Click on the
Add Custom MCP.
- Add the name (i.e.,
Claude Context) and server configuration from below, and make sure to hit the Install button.
{
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
- Save the server by hitting the
Install button.
LangChain/LangGraph
For LangChain/LangGraph integration examples, see this example.
Other MCP Clients
The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP - compatible client by running:
npx @zilliz/claude-context-mcp@latest
Usage in Your Codebase
- Open Claude Code
cd your-project-directory
claude
- Index your codebase:
Index this codebase
- Check indexing status:
Check the indexing status
- Start searching:
Find functions that handle user authentication
🎉 That's it! You now have semantic code search in Claude Code.
Environment Variables Configuration
For more detailed MCP environment variable configuration, see our Environment Variables Guide.
Using Different Embedding Models
To configure custom embedding models (e.g., text-embedding-3-large for OpenAI, voyage-code-3 for VoyageAI), see the MCP Configuration Examples for detailed setup instructions for each provider.
File Inclusion & Exclusion Rules
For a detailed explanation of file inclusion and exclusion rules, and how to customize them, see our File Inclusion & Exclusion Rules.
Available Tools
1. index_codebase
Index a codebase directory for hybrid search (BM25 + dense vector).
2. search_code
Search the indexed codebase using natural language queries with hybrid search (BM25 + dense vector).
3. clear_index
Clear the search index for a specific codebase.
4. get_indexing_status
Get the current indexing status of a codebase. Shows progress percentage for actively indexing codebases and completion status for indexed codebases.
📊 Evaluation
Our controlled evaluation demonstrates that Claude Context MCP achieves ~40% token reduction under the condition of equivalent retrieval quality. This translates to significant cost and time savings in production environments. It also means that, under the constraint of limited token context length, using Claude Context yields better retrieval and answer results.
For detailed evaluation methodology and results, see the evaluation directory.
🔧 Technical Details
🔍 Implementation Details
- 🔍 Hybrid Code Search: Ask questions like "find functions that handle user authentication" and get relevant, context - rich code instantly using advanced hybrid search (BM25 + dense vector).
- 🧠 Context - Aware: Discover large codebases, understand how different parts of your codebase relate, even across millions of lines of code.
- ⚡ Incremental Indexing: Efficiently re - index only changed files using Merkle trees.
- 🧩 Intelligent Code Chunking: Analyze code in Abstract Syntax Trees (AST) for chunking.
- 🗄️ Scalable: Integrates with Zilliz Cloud for scalable vector search, regardless of the size of your codebase.
- 🛠️ Customizable: Configure file extensions, ignore patterns, and embedding models.
Core Components
Claude Context is a monorepo containing three main packages:
@zilliz/claude-context-core: Core indexing engine with embedding and vector database integration- VSCode Extension: Semantic Code Search extension for Visual Studio Code
@zilliz/claude-context-mcp: Model Context Protocol server for AI agent integration
Supported Technologies
- Embedding Providers: OpenAI, VoyageAI, Ollama, Gemini
- Vector Databases: Milvus or Zilliz Cloud(fully managed vector database as a service)
- Code Splitters: AST - based splitter (with automatic fallback), LangChain character - based splitter
- Languages: TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, Markdown
- Development Tools: VSCode, Model Context Protocol
📦 Other Ways to Use Claude Context
While MCP is the recommended way to use Claude Context with AI assistants, you can also use it directly or through the VSCode extension.
Build Applications with Core Package
The @zilliz/claude-context-core package provides the fundamental functionality for code indexing and semantic search.
import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';
const embedding = new OpenAIEmbedding({
apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
model: 'text-embedding-3-small'
});
const vectorDatabase = new MilvusVectorDatabase({
address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});
const context = new Context({
embedding,
vectorDatabase
});
const stats = await context.indexCodebase('./your-project', (progress) => {
console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
console.log(`Content: ${result.content.substring(0, 100)}...`);
});
VSCode Extension
Integrates Claude Context directly into your IDE. Provides an intuitive interface for semantic code search and navigation.
- Direct Link: Install from VS Code Marketplace
- Manual Search:
- Open Extensions view in VSCode (Ctrl + Shift + X or Cmd + Shift + X on Mac)
- Search for "Semantic Code Search"
- Click Install
🛠️ Development
Setup Development Environment
Prerequisites
- Node.js 20.x or 22.x
- pnpm (recommended package manager)
Cross - Platform Setup
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
pnpm install
pnpm build
pnpm dev
Windows - Specific Setup
On Windows, ensure you have:
- Git for Windows with proper line - ending configuration
- Node.js installed via the official installer or package manager
- pnpm installed globally:
npm install -g pnpm
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
git config core.autocrlf false
pnpm install
pnpm build
pnpm dev
Building
pnpm build
pnpm build:core
pnpm build:vscode
pnpm build:mcp
pnpm benchmark
Windows Build Notes
- All build scripts are cross - platform compatible using rimraf.
- Build caching is enabled for faster subsequent builds.
- Use PowerShell or Command Prompt - both work equally well.
Running Examples
cd examples/basic-usage
pnpm dev
📖 Examples
Check the /examples directory for complete usage examples:
- Basic Usage: Simple indexing and search example
❓ FAQ
Common Questions:
- What files does Claude Context decide to embed?
- Can I use a fully local deployment setup?
- Does it support multiple projects / codebases?
- How does Claude Context compare to other coding tools?
❓ For detailed answers and more troubleshooting tips, see our FAQ Guide.
🔧 Encountering issues? Visit our Troubleshooting Guide for step - by - step solutions.
📚 Need more help? Check out our complete documentation for detailed guides and troubleshooting tips.
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details on how to get started.
Package - specific contributing guides:
- Core Package Contributing
- MCP Server Contributing
- VSCode Extension Contributing
🗺️ Roadmap
- [x] AST - based code analysis for improved understanding
- [x] Support for additional embedding providers
- [ ] Agent - based interactive search mode
- [x] Enhanced code chunking strategies
- [ ] Search result ranking optimization
- [ ] Robust Chrome Extension
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🔗 Links
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
