claude-context README

The project's README from github.com/zilliztech/claude-context. As one markdown file: README.md.

🆕 Looking for persistent memory for Claude Code? Check out memsearch Claude Code plugin — a markdown-first memory system that gives your AI agent long-term memory across sessions.

Your entire codebase as Claude's context

License Node.js Documentation VS Code Marketplace npm - core npm - mcp Twitter DeepWiki discord zilliztech/claude-context | Trendshift

Claude Context is an MCP plugin that adds semantic code search to Claude Code and other AI coding agents, giving them deep context from your entire codebase.

🧠 Your Entire Codebase as Context: Claude Context uses semantic search to find all relevant code from millions of lines. No multi-round discovery needed. It brings results straight into the Claude's context.

💰 Cost-Effective for Large Codebases: Instead of loading entire directories into Claude for every request, which can be very expensive, Claude Context efficiently stores your codebase in a vector database and only uses related code in context to keep your costs manageable.

🚀 Demo

img

Model Context Protocol (MCP) allows you to integrate Claude Context with your favorite AI coding assistants, e.g. Claude Code.

Quick Start

Prerequisites

Get a free vector database on Zilliz Cloud 👈

Claude Context needs a vector database. You can sign up on Zilliz Cloud to get 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 look like this: it always starts 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:

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_ADDRESS=your-zilliz-cloud-public-endpoint \
  -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:

  1. Create or edit the ~/.codex/config.toml file.

  2. Add the following configuration:

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[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" }
# Optional: override the default 10s startup timeout
startup_timeout_ms = 20000
  1. Save the file and restart Codex CLI to apply the changes.
Gemini CLI

Gemini CLI requires manual configuration through a JSON file:

  1. Create or edit the ~/.gemini/settings.json file.
  2. 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"
      }
    }
  }
}
  1. 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

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

{
  "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:

  1. Navigate to Settings → MCP Servers → Add Server.
  2. Fill in the server details:
    • Name: claude-context
    • Type: STDIO
    • Command: npx
    • Arguments: ["-y", "@zilliz/claude-context-mcp@latest"]
    • Environment Variables:
      • OPENAI_API_KEY: your-openai-api-key
      • MILVUS_ADDRESS: your-zilliz-cloud-public-endpoint
      • MILVUS_TOKEN: your-zilliz-cloud-api-key
  3. 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:

  1. Open Cline and click on the MCP Servers icon in the top navigation bar.

  2. Select the Installed tab, then click Advanced MCP Settings.

  3. 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"
      }
    }
  }
}
  1. 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

  1. Click the hamburger menu.

  2. Select Settings.

  3. Navigate to the Tools section.

  4. Click the + Add MCP button.

  5. Enter the following command:

    npx @zilliz/claude-context-mcp@latest

  6. Name the MCP: Claude Context.

  7. Click the Add button.

B. Manual Configuration

  1. Press Cmd/Ctrl Shift P or go to the hamburger menu in the Augment panel
  2. Select Edit Settings
  3. Under Advanced, click Edit in settings.json
  4. 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:

  1. Open Roo Code and navigate to Settings → MCP Servers → Edit Global Config.

  2. 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"
      }
    }
  }
}
  1. 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.

  1. Go to the Zencoder menu (...)
  2. From the dropdown menu, select Tools
  3. Click on the Add Custom MCP
  4. 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"
    }
}
  1. 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

  1. Open Claude Code

    cd your-project-directory
claude

  2. Index your codebase:

    Index this codebase

  3. Check indexing status:

    Check the indexing status

  4. 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 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. This also means that, under the constraint of limited token context length, using Claude Context yields better retrieval and answer results.

MCP Efficiency Analysis

For detailed evaluation methodology and results, see the evaluation directory.

🏗️ Architecture

🔧 Implementation Details

Core Components

Claude Context is a monorepo containing three main packages:

Supported Technologies

📦 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';

// Initialize embedding provider
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

// Initialize vector database
const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

// Create context instance
const context = new Context({
    embedding,
    vectorDatabase
});

// Index your codebase with progress tracking
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Perform semantic search
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.

  1. Direct Link: Install from VS Code Marketplace
  2. Manual Search:
    • Open Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X on Mac)
    • Search for "Semantic Code Search"
    • Click Install

img

🛠️ Development

Setup Development Environment

Prerequisites

Cross-Platform Setup

# Clone repository
git clone https://github.com/zilliztech/claude-context.git
cd claude-context

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start development mode
pnpm dev

Windows-Specific

claude-context (zilliztech/claude-context)

bm25
Searching Database…

12.6K ·GitHub
Claude-context
What is this?Claude Context is an MCP server that gives AI coding agents semantic search over your entire codebase, so they can pull relevant code straight into context instead of loading whole directories.
Is this an MCP server, a VS Code extension, or something else?It is all three: a monorepo with an MCP server package, a VSCode extension ('Semantic Code Search'), and a reusable core indexing/search library you can build your own apps on.
How do I add it to Claude Code?Use the CLI to register the MCP server with Claude Code, or add the equivalent JSON/TOML config to other clients like Cursor, Codex CLI, Gemini CLI or Claude Desktop.
What do I need before I can use it — just Node.js?You need Node.js 20+, an OpenAI API key for the embedding model, and a vector database — easiest is a free Zilliz Cloud account (or self-hosted Milvus).
Any catches before I index my whole codebase?It's not fully self-contained — you're dependent on an external embedding API (OpenAI/VoyageAI/Ollama/Gemini) and a vector database, so indexing costs API calls and requires sign-ups rather than running entirely offline out of the box.
Which coding agents and editors does it actually plug into?It documents setup for Claude Code, OpenAI Codex CLI, Gemini CLI, Qwen Code, Cursor, Void, Claude Desktop, Windsurf, VS Code, Cherry Studio, Cline, Augment, Roo Code and Zencoder, plus any generic MCP-compatible client over stdio.
What languages can it actually index and search?It parses code into AST-based chunks for TypeScript, JavaScript, Python, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala and Markdown, with a LangChain character-based splitter as fallback.
How does it avoid re-indexing the whole repo every time?It uses Merkle trees for incremental indexing, so after the first full pass only changed files are re-indexed.
Can I swap the embedding model or vector store?Yes — embeddings can come from OpenAI, VoyageAI, Ollama or Gemini, and the vector store can be self-hosted Milvus or managed Zilliz Cloud.
Does this actually save tokens compared to dumping files into context?The project's own evaluation reports about 40% token reduction versus loading full directories, at equivalent retrieval quality.
What are similar projects?agentic-rag-for-dummies, xerj, memex, Baize, docker-agent, headroom, memory-lancedb-pro, lean-ctx
Which topics is it in?agentic-rag, embedding, code-search, hybrid-search, ast, bm25, langgraph, vibe-coding, codex-cli, vscode-extension, vector-search, gemini-cli
Creator
zilliztech
Size
7.6 MB
Stars
12.6K
Updated
CommitJul 14
Age
1y
Commits · 90 Days