Claude Context: Getting Started—Help AI Truly Understand Your Entire Codebase

Claude Context is an open-source MCP (Model Context Protocol) plugin developed by the vector database vendor Zilliz. Its core purpose is crystal clear: inject an AI coding assistant with semantic understanding of your entire codebase.

In traditional workflows, if you want an AI to help you understand a new, unfamiliar codebase, you usually have to manually copy file paths, describe the project structure, and explain the relationships between modules—things that, in principle, the AI should be able to do itself. With Claude Context, semantic search lets the AI directly query functions, classes, and data structures inside your codebase, without relying on you to manually inject context.

This project is hosted on GitHub at zilliztech/claude-context and is released under the MIT License, with the full codebase open-sourced.

---

Difficulty / Time / Takeaways

Beginner-friendly | About 20 minutes | You’ll learn how to give any coding tool semantic understanding for millions of lines of code with just 2 commands—while reducing token usage by about 40%.

---

Target Audience

• Developers who use AI programming tools like Claude Code, Cursor, Windsurf, Cline, etc. in daily work
• People who have a basic understanding of RAG (Retrieval-Augmented Generation) and vector search and want to put it into practice deeply
• Teams looking to lower token costs and improve the accuracy of AI responses

---

Core Dependencies & Environment

System Requirements

• Node.js >= 20.0.0 and < 24.0.0
• OS: macOS, Windows, or Linux—any is fine

Service Dependencies

• Zilliz Cloud (free quota is enough for personal use): provides the vector database backend
• OpenAI API Key: used to generate vectors with the embedding model (you can also replace it with other embedding providers that support the same use case)

---

Full Project Directory Tree

Claude Context is a pure npm package—there’s no need for you to clone or build any local code. After installation, it will manage its own storage structure:

~/.claude/
└── plugins/
    └── claude-context/          # MCP plugin directory
        └── [Indexed data files] # Incremental Merkle tree snapshots

If you integrate the Core package directly into your application, the structure looks like this:

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # Stores API Key
└── your-codebase/              # Codebase to be indexed

---

Step-by-Step

Step 1: Register Zilliz Cloud and get vector database credentials

Claude Context’s vector storage depends on Zilliz Cloud (or self-hosted Milvus). You’ll need to create a free account for this step.

Open zilliz.com/cloud and register using your email or GitHub account. After logging in, create a new Serverless Cluster in the console:

1. Click Create Cluster
2. Select Serverless (the free tier is fully sufficient)
3. Choose the nearest region (AWS us-west-2 or Singapore are commonly used)
4. Name your cluster, for example: claude-context

Once the cluster is created, go to the cluster details page, find Connection Info, and copy the following two values for later use:

• Public Endpoint: something like https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key: something like xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Get an OpenAI API Key

Claude Context uses an embedding model to convert code snippets into vectors. You need to prepare an OpenAI API Key to power the default text-embedding-3-small model.

Open platform.openai.com/api-keys, click Create new secret key, and copy the generated value (format: sk-xxxxxxxx...).

Step 3: Install the Claude Context MCP into Claude Code

Now we register this MCP server inside Claude Code. Open your terminal, go to any project directory, and run the following commands:

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

Replace the placeholders with your actual values:

• sk-your-openai-api-key → your OpenAI API Key
• your-zilliz-cloud-api-key → your Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → your Zilliz Public Endpoint

If the command runs successfully, you should see that the MCP server is registered. To verify the installation:

claude mcp list

You should see claude-context in the list with the status set to running.

If you’re using a different AI coding tool, the setup is slightly different. Here are a few common scenarios:

Cursor (recommended: file-based configuration):

// ~/.cursor/mcp.json
{
  "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"
      }
    }
  }
}

Windsurf (also uses JSON configuration):

// ~/.windsurf/mcp_settings.json
{
  "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"
      }
    }
  }
}

Step 4: Index your first codebase

After installation, go into your project directory and start Claude Code:

cd your-project-directory
claude

In the chat, enter the following command to trigger indexing:

Index this codebase

Claude Context will start analyzing your codebase immediately. The process consists of two phases:

1. File scanning: traverses directories and filters code files to process based on file extensions
2. Vector embeddings: for each code file, splits it into chunks using AST (abstract syntax tree) chunking, calls the embedding model to generate vectors, and stores them in the vector database

During indexing, you can ask about progress at any time:

Check the indexing status

The response will tell you the current index progress percentage and how many files have been completed.

Step 5: Validate search results and understand the output

Once indexing is complete, you can start semantic search. Here are a few common query scenarios:

Find the implementation of a specific feature:

Find functions that handle user authentication

The results will include relevant function names, file paths, code snippets, and a relevance score (between 0 and 1; the higher, the more relevant).

Understand relationships between modules:

How does the payment module connect to the order module?

Quickly locate configuration-related code:

Where is the database connection pool configured?

The results are formatted like this:

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

If you want to clear the index and start over, run:

Clear the index for this codebase

---

Troubleshooting FAQ

Q1: Node.js version incompatibility—command fails

Symptoms: claude mcp add fails, or the MCP server exits immediately after starting.

Cause: Claude Context currently does not support Node.js 24.x.

Solution:

# Check your current Node version
node -v

# If it’s 24.x, downgrade to 20.x (LTS)
nvm install 20
nvm use 20

Q2: Incorrect environment variable configuration—indexing fails

Symptoms: Index this codebase shows no response or returns an error like Milvus connection failed.

Check these:

1. Confirm MILVUS_ADDRESS does not include the https:// prefix—use only the host portion
2. Confirm MILVUS_TOKEN exactly matches the API Key shown in the Zilliz Cloud console
3. Confirm OPENAI_API_KEY starts with sk-

Correct format example:

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Q3: Indexing progress is stuck with no advancement

Symptoms: After the indexing command is issued, it never responds.

Solution:

1. First run Check the indexing status to confirm the current state
2. Check network connectivity (you need access to both the OpenAI API and Zilliz Cloud)
3. If the cluster was just created, the endpoint may still be initializing—wait 1–2 minutes and try again

Q4: Search results are empty or completely irrelevant

Symptoms: Queries that should match content return no results.

Cause: The index files may be incomplete, or the query wording differs significantly from the naming used in the code.

Solution:

1. Check the index status first: Check the indexing status
2. Try a more specific query (use the actual variable names or function names that exist in the code)
3. If you confirm the code exists but search can’t find it, clear the index and re-index:

Clear the index for this codebase
Index this codebase

Q5: Incremental indexing isn’t taking effect—modified code isn’t being retrieved

Symptoms: You changed a file, but semantic search results still point to the old version.

Cause: Claude Context uses Merkle tree snapshots to detect file changes. If you manually delete the snapshot files, incremental detection may fail.

Solution: Clear the index and start over:

Clear the index for this codebase
Index this codebase

Q6: MCP connection fails—tools are unavailable

Symptoms: In the tool list, you can’t find tools like search_code or index_codebase.

Solution:

1. Restart Claude Code (sometimes the MCP server needs to be reloaded)
2. Confirm there are no syntax errors in your MCP configuration (JSON: watch out for commas and quotes)
3. Check whether the plugin status in claude mcp list is running

claude mcp list

If the status is stopped, restart manually:

claude mcp remove claude-context
# Then rerun the installation command from Step 3

---

Further Reading / Advanced Directions

Use a Custom Embedding Model

OpenAI’s text-embedding-3-small is the default choice, but Claude Context supports multiple embedding providers, enabling fully localized deployments:

Use Ollama (local model):

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Use VoyageAI:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Integrate LangChain/LangGraph for Advanced RAG

If you want to integrate Claude Context directly into your own application, you can use the Core package:

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// Initialize embedding and the vector database
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 });

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

// Run 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)}...`);
});

For detailed examples, refer to evaluation/retrieval/custom.py。

VSCode Visualization for Search

If you prefer to work directly inside your IDE, you can install the Semantic Code Search extension. It lets you perform semantic search within VS Code without needing to start Claude Code.

Strategies for Managing Multiple Codebases

Claude Context supports indexing and managing multiple codebases at the same time. Just call Index this codebase in different directories—each directory will maintain its own separate index. You can use the directory name to distinguish them:

# Working directory A
cd ~/projects/frontend && claude
# In the chat, execute Index this codebase

# Working directory B
cd ~/projects/backend && claude
# In the chat, execute Index this codebase

How AST Chunking and Merkle Tree Incremental Indexing Work

Claude Context’s code understanding capability is built on two core technologies:

• AST-based Chunking: uses an abstract syntax tree to analyze code structure and splits by function, class, and module boundaries—rather than simply slicing by line count. This ensures each chunk is a semantically complete unit of code.
• Merkle tree incremental indexing: after each file changes, Claude Context uses Merkle tree comparisons to re-index only the changed files instead of rebuilding everything from scratch. This greatly reduces maintenance costs for large codebases.

If you’re interested in implementation details of these two technologies, you can check the packages/core source code in the zilliztech/claude-context repository.