Environment Variables Reference

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/utils/env-manager.ts
• packages/mcp/README.md
• packages/core/README.md
• examples/basic-usage/index.ts
• README.md

Environment variables serve as the primary configuration mechanism for Claude Context across its various implementations, including the core engine, Model Context Protocol (MCP) server, and example applications. These variables manage sensitive credentials for embedding providers (OpenAI, VoyageAI, Gemini, Ollama) and connection parameters for the Milvus vector database.

The project utilizes a tiered configuration approach where variables can be passed via the system environment or persisted in a local configuration file managed by a dedicated utility.

Sources: README.md, packages/core/src/utils/env-manager.ts:1-13, packages/mcp/README.md

Environment Management Architecture

The EnvManager class in the core package handles the retrieval and persistence of configuration values. It implements a specific priority logic: it first attempts to read from process.env. If a value is not present, it searches a local .env file located in the user's home directory under ~/.context/.env.

Sources: packages/core/src/utils/env-manager.ts:5-24

Configuration Lookup Flow

The following diagram illustrates the sequence of checks performed when the system requests a configuration value:

The logic ensures that runtime environment variables always override persisted local settings.
Sources: packages/core/src/utils/env-manager.ts:15-37

Core Configuration Variables

These variables are essential for the operation of the core indexing engine and are used across the MCP server and basic examples.

Variable	Description	Default / Example
OPENAI_API_KEY	Authentication key for OpenAI embedding models.	sk-...
MILVUS_ADDRESS	Public endpoint or host for the Milvus vector database.	localhost:19530
MILVUS_TOKEN	API key or token for Zilliz Cloud / Milvus authentication.	your-token
SPLITTER_TYPE	Defines the code splitting strategy (ast or langchain).	ast

Sources: examples/basic-usage/index.ts:25-50, packages/core/README.md, packages/mcp/README.md

Embedding Provider Configuration

Claude Context supports multiple embedding providers, each requiring specific environment variables for connectivity and model selection.

OpenAI (Default)

Required for generating vectors via OpenAI services.

• OPENAI_API_KEY: Required.
• EMBEDDING_MODEL: Optional. Defaults to text-embedding-3-small.
• OPENAI_BASE_URL: Optional. Used for proxying or Azure OpenAI compatibility.

Sources: packages/mcp/README.md, packages/core/README.md

VoyageAI

Optimized for code-specific embeddings.

• VOYAGEAI_API_KEY: Required for VoyageAI access.
• EMBEDDING_MODEL: Optional. Defaults to voyage-code-3.

Sources: packages/mcp/README.md, packages/core/README.md

Gemini & Ollama

• Gemini: Requires GEMINI_API_KEY and optional GEMINI_BASE_URL.
• Ollama (Local): Requires EMBEDDING_MODEL (e.g., nomic-embed-text) and OLLAMA_HOST (defaults to http://127.0.0.1:11434).

Sources: packages/mcp/README.md

Advanced Processing Settings

The MCP server and core engine support additional variables to tune indexing performance and file inclusion rules.

Batching and Performance

• EMBEDDING_BATCH_SIZE: Sets the number of chunks processed in a single embedding request. Defaults to 100.
• EMBEDDING_PROVIDER: Explicitly selects the provider (values: OpenAI, VoyageAI, Gemini, Ollama).

Sources: packages/mcp/README.md

File Inclusion & Exclusion

These variables extend the default rules for file processing:

• CUSTOM_EXTENSIONS: Comma-separated list of additional extensions (e.g., .vue,.svelte).
• CUSTOM_IGNORE_PATTERNS: Comma-separated glob patterns to exclude from indexing (e.g., temp/**,*.backup).

Sources: packages/mcp/README.md

Persistence Implementation

The EnvManager provides a set method that ensures the configuration directory exists and maintains the .env file structure.

// From packages/core/src/utils/env-manager.ts
set(name: string, value: string): void {
    const envDir = path.dirname(this.envFilePath);
    if (!fs.existsSync(envDir)) {
        fs.mkdirSync(envDir, { recursive: true });
    }
    // ... logic to read, update or append variable
    fs.writeFileSync(this.envFilePath, content, 'utf-8');
}

Sources: packages/core/src/utils/env-manager.ts:43-85

Conclusion

The environment variable system provides a flexible, secure way to manage project dependencies and credentials. By utilizing the EnvManager for local persistence and supporting standard system environment variables, Claude Context can be easily integrated into various developer workflows, from local CLI usage to managed MCP server deployments.

Sources: README.md, packages/mcp/README.md