Skip to content

csawicz/aws-claude-context

BranchesTags

Repository files navigation

Your entire codebase as Claude's context

License Node.js Documentation VS Code Marketplace npm - core npm - mcp Twitter DeepWiki discord

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.

⚡ AWS-Powered by Default: Uses AWS Bedrock (amazon.titan-embed-text-v2:0) for embeddings and S3Vectors for lightning-fast vector search.

🚀 Quick Start: claude mcp add claude-context -e AWS_REGION=us-east-1 -e S3_VECTORS_BUCKET_NAME=your-bucket -- npx @zilliz/claude-context-mcp@latest

🚀 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

AWS Setup (Recommended)

Claude Context now defaults to AWS services when AWS credentials are available:

  • AWS Bedrock for text embeddings (Amazon Titan Text Embeddings V2)
  • AWS S3Vectors for optimized vector storage and search
AWS Configuration (Recommended) 👈

  1. Set up AWS credentials using any of these methods:

    • AWS credentials file (~/.aws/credentials)
    • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
    • IAM roles (for EC2 instances)
    • AWS CLI configuration

  2. Create an S3Vectors bucket in your AWS account:

    aws s3vectors create-vector-bucket --vector-bucket-name claude-context-vectors

  3. Set environment variables:

    export AWS_REGION=us-east-1
export S3_VECTORS_BUCKET_NAME=my-claude-context-vectors
# Optional: Bedrock model (defaults to amazon.titan-embed-text-v2:0)
export BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0

Required AWS permissions:

  • bedrock:InvokeModel (for embeddings)
  • s3vectors:* (for vector operations)

Legacy Setup Options

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:

  • Node.js >= 20.0.0 and < 24.0.0 (NOT compatible with Node.js 24.0.0)
  • pnpm >= 10.0.0 (for development)

📋 Complete Setup Guide: See CLAUDE_CODE_SETUP.md for detailed build and development instructions.

Quick Configuration

AWS Setup (Recommended):

# 1. Configure AWS credentials (using AWS CLI or environment variables)
aws configure  # or export AWS_REGION=us-east-1

# 2. Create S3Vectors bucket
aws s3vectors create-vector-bucket --vector-bucket-name claude-context-vectors

# 3. Add Claude Context MCP server to Claude Code
claude mcp add claude-context \
  -e AWS_REGION=us-east-1 \
  -e S3_VECTORS_BUCKET_NAME=claude-context-vectors \
  -- npx @zilliz/claude-context-mcp@latest

Development/Local Build:

# 1. Clone and build
git clone https://github.com/zilliztech/claude-context.git
cd claude-context && pnpm install && pnpm build

# 2. Add local build to Claude Code
claude mcp add claude-context-dev \
  -e AWS_REGION=us-east-1 \
  -e S3_VECTORS_BUCKET_NAME=claude-context-vectors \
  -- node ./packages/mcp/dist/index.js

Legacy OpenAI + Zilliz Cloud Setup:

claude mcp add claude-context \
  -e OPENAI_API_KEY=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 (Gemini CLI, Cursor, Windsurf, etc.)

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

Add claude-context MCP server to 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: ["@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.
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

For more detailed MCP environment variable configuration, see our Environment Variables Guide.

📚 Need more help? Check out our complete documentation for detailed guides and troubleshooting tips.

🏗️ Architecture

🔧 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 codebase, 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, no matter how large your codebase is.
  • 🛠️ 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: AWS Bedrock (default), OpenAI, VoyageAI, Ollama, Gemini
  • Vector Databases: AWS S3Vectors (default), Milvus, or Zilliz Cloud
  • 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.

AWS Setup (Recommended):

import { Context, S3VectorsDatabase, BedrockEmbedding } from '@zilliz/claude-context-core';

// Initialize AWS Bedrock embedding provider
const embedding = new BedrockEmbedding({
    region: process.env.AWS_REGION || 'us-east-1',
    model: 'amazon.titan-embed-text-v2:0'
});

// Initialize S3Vectors database
const vectorDatabase = new S3VectorsDatabase({
    bucketName: process.env.S3_VECTORS_BUCKET_NAME || 'my-claude-context-vectors',
    region: process.env.AWS_REGION || 'us-east-1'
});

// Create context instance (or use automatic configuration)
const context = new Context({ embedding, vectorDatabase });
// Or let Context auto-configure based on environment variables:
// const context = new Context(); // Uses AWS services if AWS credentials available

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

Legacy Setup:

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 });

// Same indexing and search API...

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

📋 Complete Setup Guide: See CLAUDE_CODE_SETUP.md for detailed Claude Code integration instructions.

Setup Development Environment

Prerequisites:

  • Node.js >= 20.0.0 and < 24.0.0 (NOT compatible with Node.js 24.0.0)
  • pnpm >= 10.0.0
  • AWS credentials configured (for testing AWS features)
# 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 with file watching
pnpm dev

Test with Claude Code

After building, test your local changes with Claude Code:

# Add local build to Claude Code
claude mcp add claude-context-dev \
  -e AWS_REGION=us-east-1 \
  -e S3_VECTORS_BUCKET_NAME=your-bucket \
  -- node ./packages/mcp/dist/index.js

Building

# Build all packages
pnpm build

# Build specific package
pnpm build:core
pnpm build:vscode
pnpm build:mcp

Running Examples

# Development with file watching
cd examples/basic-usage
pnpm dev

Supported File Extensions

By default, Claude Context supports:

  • Programming languages: .ts, .tsx, .js, .jsx, .py, .java, .cpp, .c, .h, .hpp, .cs, .go, .rs, .php, .rb, .swift, .kt, .scala, .m, .mm
  • Documentation: .md, .markdown, .ipynb

Ignore Patterns

Common directories and files are automatically ignored:

  • Build outputs: node_modules/**, dist/**, build/**, out/**, target/**, coverage/**, .nyc_output/**
  • Version control: .git/**, .svn/**, .hg/**
  • IDE/Editor files: .vscode/**, .idea/**, *.swp, *.swo
  • Cache directories: .cache/**, __pycache__/**, .pytest_cache/**
  • Logs and temporary: logs/**, tmp/**, temp/**, *.log
  • Environment files: .env, .env.*, *.local
  • Minified/bundled files: *.min.js, *.min.css, *.bundle.js, *.bundle.css, *.chunk.js, *.map

See FAQ Guide for detailed and customized configuration of supported file extensions and ignore patterns.

📖 Examples

Check the /examples directory for complete usage examples:

  • Basic Usage: Simple indexing and search example

❓ FAQ

Common Questions:

For detailed answers and more troubleshooting tips, see our FAQ Guide.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Package-specific contributing guides:

🗺️ Roadmap

  • AST-based code analysis for improved understanding
  • Support for additional embedding providers
  • Agent-based interactive search mode
  • 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

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages