Skip to content

environment-variables.md

Latest commit

 

History

History
114 lines (90 loc) · 5.46 KB

environment-variables.md

File metadata and controls

114 lines (90 loc) · 5.46 KB
Raw

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: