Environment Variables Configuration

🎯 Global Configuration

Claude Context supports a global configuration file at ~/.context/.env to simplify MCP setup across different MCP clients.

Benefits:

• Configure once, use everywhere
• No need to specify environment variables in each MCP client
• Cleaner MCP configurations

📋 Environment Variable Priority

1. Process Environment Variables (highest)
2. Global Configuration File (~/.context/.env)
3. Default Values (lowest)

🔧 Required Environment Variables

Embedding Provider

Variable	Description	Default
EMBEDDING_PROVIDER	Provider: OpenAI, VoyageAI, Gemini, Ollama	OpenAI
EMBEDDING_MODEL	Embedding model name (works for all providers)	Provider-specific default
OPENAI_API_KEY	OpenAI API key	Required for OpenAI
OPENAI_BASE_URL	OpenAI API base URL (optional, for custom endpoints)	https://api.openai.com/v1
VOYAGEAI_API_KEY	VoyageAI API key	Required for VoyageAI
GEMINI_API_KEY	Gemini API key	Required for Gemini
GEMINI_BASE_URL	Gemini API base URL (optional, for custom endpoints)	https://generativelanguage.googleapis.com/v1beta

💡 Note: EMBEDDING_MODEL is a universal environment variable that works with all embedding providers. Simply set it to the model name you want to use (e.g., text-embedding-3-large for OpenAI, voyage-code-3 for VoyageAI, etc.).

Supported Model Names:

• OpenAI Models: See getSupportedModels in openai-embedding.ts for the full list of supported models.

• VoyageAI Models: See getSupportedModels in voyageai-embedding.ts for the full list of supported models.

• Gemini Models: See getSupportedModels in gemini-embedding.ts for the full list of supported models.

• Ollama Models: Depends on the model you install locally.

📖 For detailed provider-specific configuration examples and setup instructions, see the MCP Configuration Guide.

Vector Database

Variable	Description	Default
MILVUS_TOKEN	Milvus authentication token. Get Zilliz Personal API Key	Recommended
MILVUS_ADDRESS	Milvus server address. Optional when using Zilliz Personal API Key	Auto-resolved from token
MILVUS_COLLECTION_LIMIT_CHECK_TIMEOUT_MS	Timeout for gRPC pre-check in checkCollectionLimit() before indexing begins	15000

Ollama (Optional)

Variable	Description	Default
OLLAMA_HOST	Ollama server URL	http://127.0.0.1:11434
OLLAMA_MODEL(alternative to EMBEDDING_MODEL)	Model name

Advanced Configuration

Variable	Description	Default
HYBRID_MODE	Enable hybrid search (BM25 + dense vector). Set to false for dense-only search	true
EMBEDDING_BATCH_SIZE	Batch size for processing. Larger batch size means less indexing time	100
SPLITTER_TYPE	Code splitter type: ast, langchain	ast
CUSTOM_EXTENSIONS	Additional file extensions to include (comma-separated, e.g., .vue,.svelte,.astro)	None
CUSTOM_IGNORE_PATTERNS	Additional ignore patterns (comma-separated, e.g., temp/**,*.backup,private/**)	None
CODE_CHUNKS_COLLECTION_NAME_OVERRIDE	Optional custom prefix for collection names. Produces code_chunks_<suffix>_<pathHash> or hybrid_code_chunks_<suffix>_<pathHash> after sanitization. The path hash stays appended so collections remain unique per codebase even when the override is set	None

When CODE_CHUNKS_COLLECTION_NAME_OVERRIDE is set, Claude Context writes to an override-named collection instead of the default code_chunks_<pathHash>. The per-codebase <pathHash> suffix is preserved to keep multiple codebases distinct under the same override. If you later unset the variable, Claude Context returns to the plain hash-based naming for that path.

🚀 Quick Setup

1. Create Global Config

mkdir -p ~/.context
cat > ~/.context/.env << 'EOF'
EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
EMBEDDING_MODEL=text-embedding-3-small
MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
MILVUS_TOKEN=your-zilliz-cloud-api-key
EOF

See the Example File for more details.

2. Simplified MCP Configuration

Claude Code:

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

Cursor/Windsurf/Others:

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"]
    }
  }
}

📚 Additional Information

For detailed information about file processing rules and how custom patterns work, see:

• What files does Claude Context decide to embed?