Environment Variables Reference

This reference covers the environment variables actually used by QDrant Loader and its MCP server. Environment variables provide a secure way to configure credentials and basic settings.

🎯 Overview

QDrant Loader uses environment variables in two ways:

Direct usage - Variables read directly by the application code
Config substitution - Variables substituted into YAML configuration files using ${VARIABLE_NAME} syntax

Configuration Priority

1. Command-line arguments (highest priority)
2. Environment variables ← This guide
3. Configuration file
4. Default values (lowest priority)

🔧 Environment Variables Used Directly by Code

These environment variables are read directly by the application code:

QDrant Database Connection (MCP Server)

QDRANT_URL

Description: URL of your QDrant database instance
Used by: MCP server configuration
Required: No (defaults to http://localhost:6333)
Format: http://host:port or https://host:port
Examples:

export QDRANT_URL="http://localhost:6333"
export QDRANT_URL="https://your-cluster.qdrant.io"

QDRANT_API_KEY

Description: API key for QDrant Cloud or secured instances
Used by: MCP server configuration
Required: No (only for secured QDrant instances)
Format: String
Examples:

export QDRANT_API_KEY="your-qdrant-cloud-api-key"

QDRANT_COLLECTION_NAME

Description: Name of the QDrant collection to use
Used by: MCP server configuration
Required: No (defaults to "documents")
Format: String (alphanumeric, underscores, hyphens)
Examples:

export QDRANT_COLLECTION_NAME="documents"
export QDRANT_COLLECTION_NAME="my_project_docs"

LLM Provider (Unified)

LLM_PROVIDER

Description: LLM provider identifier
Used by: Both apps (via config loader or file substitution)
Required: Yes (set explicitly or in config)
Examples:

export LLM_PROVIDER="openai"      # or ollama, openai_compat, custom

LLM_BASE_URL

Description: Base URL for the provider's API (OpenAI-compatible or native)
Required: Yes for custom/compat endpoints; Ollama default is http://localhost:11434

export LLM_BASE_URL="https://api.openai.com/v1"
export LLM_BASE_URL="http://localhost:11434/v1"   # Ollama OpenAI-compatible

LLM_API_KEY

Description: API key for the provider
Required: When provider needs auth (OpenAI and most hosted compat endpoints)

export LLM_API_KEY="sk-your-openai-api-key"

LLM_EMBEDDING_MODEL / LLM_CHAT_MODEL

Description: Model names for embeddings and chat

export LLM_EMBEDDING_MODEL="text-embedding-3-small"
export LLM_CHAT_MODEL="gpt-4o-mini"

LLM_VECTOR_SIZE

Description: Embedding vector dimension used for collection creation

export LLM_VECTOR_SIZE=1536

Legacy: OPENAI_API_KEY remains supported for compatibility but will be superseded by LLM_API_KEY.

Data Source Authentication

CONFLUENCE_TOKEN

Description: Confluence API token for authentication
Used by: Confluence connector when not specified in config
Required: No (fallback only)
Format: String
Examples:

export CONFLUENCE_TOKEN="your-confluence-api-token"

CONFLUENCE_EMAIL

Description: Confluence user email for Cloud authentication
Used by: Confluence connector when not specified in config
Required: No (fallback only)
Format: Email address
Examples:

export CONFLUENCE_EMAIL="user@company.com"

JIRA_TOKEN

Description: JIRA API token for authentication
Used by: JIRA connector when not specified in config
Required: No (fallback only)
Format: String
Examples:

export JIRA_TOKEN="your-jira-api-token"

JIRA_EMAIL

Description: JIRA user email for Cloud authentication
Used by: JIRA connector when not specified in config
Required: No (fallback only)
Format: Email address
Examples:

export JIRA_EMAIL="user@company.com"

MCP Server Logging

MCP_LOG_LEVEL

Description: Log level for MCP server
Used by: MCP server logging configuration
Required: No (defaults to "INFO")
Format: String (DEBUG, INFO, WARNING, ERROR, CRITICAL)
Examples:

export MCP_LOG_LEVEL="INFO"
export MCP_LOG_LEVEL="DEBUG"

MCP_LOG_FILE

Description: Path to MCP server log file
Used by: MCP server logging configuration
Required: No (console only if not set)
Format: File path
Examples:

export MCP_LOG_FILE="/var/log/mcp-server.log"
export MCP_LOG_FILE="./logs/mcp.log"

MCP_DISABLE_CONSOLE_LOGGING

Description: Disable console logging for MCP server
Used by: MCP server logging configuration
Required: No (defaults to false)
Format: Boolean string ("true"/"false")
Examples:

export MCP_DISABLE_CONSOLE_LOGGING="true"

Development/Release Variables

GITHUB_TOKEN

Description: GitHub token for release automation
Used by: Release script
Required: No (only for releases)
Format: String (ghp_* or github_pat_*)
Examples:

export GITHUB_TOKEN="ghp_your-github-token"

📝 Environment Variables for Config File Substitution

These variables are substituted into YAML configuration files using ${VARIABLE_NAME} syntax. They are not read directly by the code but can be used in config files:

Common Substitution Variables

Any environment variable can be used for substitution in config files. Common examples include:

STATE_DB_PATH - Database path for state management
REPO_TOKEN - Git repository tokens
CONFLUENCE_URL - Confluence base URLs
CONFLUENCE_SPACE_KEY - Confluence space keys
CONFLUENCE_PAT - Confluence Personal Access Tokens
JIRA_URL - JIRA base URLs
JIRA_PROJECT_KEY - JIRA project keys
JIRA_PAT - JIRA Personal Access Tokens

Example config usage:

global:
  state_management:
    database_path: "${STATE_DB_PATH}"
sources:
  confluence:
    my-wiki:
      base_url: "${CONFLUENCE_URL}"
      space_key: "${CONFLUENCE_SPACE_KEY}"
      token: "${CONFLUENCE_TOKEN}"

📋 Environment File Templates

Basic .env Template

# .env - Basic configuration for MCP server
# LLM Configuration (new unified approach)
LLM_PROVIDER=openai
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-openai-api-key
LLM_EMBEDDING_MODEL=text-embedding-3-small
LLM_CHAT_MODEL=gpt-4o-mini

# Legacy (still supported)
OPENAI_API_KEY=sk-your-openai-api-key

# QDrant configuration (defaults shown)
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION_NAME=documents
# QDRANT_API_KEY=your-qdrant-cloud-api-key

# MCP Server logging (optional)
MCP_LOG_LEVEL=INFO
# MCP_LOG_FILE=./logs/mcp.log
# MCP_DISABLE_CONSOLE_LOGGING=true

Development .env Template

# .env.development - Development environment
# LLM Configuration (new unified approach)
LLM_PROVIDER=openai
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-dev-openai-api-key
LLM_EMBEDDING_MODEL=text-embedding-3-small
LLM_CHAT_MODEL=gpt-4o-mini

# Legacy (still supported)
OPENAI_API_KEY=sk-your-dev-openai-api-key

# QDrant (local development)
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION_NAME=dev_documents

# MCP Server (development settings)
MCP_LOG_LEVEL=DEBUG
MCP_LOG_FILE=./logs/mcp-dev.log

# Config file substitution variables (examples)
STATE_DB_PATH=./data/qdrant-loader.db
REPO_TOKEN=ghp_your-github-token
CONFLUENCE_URL=https://company.atlassian.net
CONFLUENCE_TOKEN=your-confluence-token
CONFLUENCE_EMAIL=dev@company.com
JIRA_URL=https://company.atlassian.net
JIRA_TOKEN=your-jira-token
JIRA_EMAIL=dev@company.com

Production .env Template

# .env.production - Production environment
# LLM Configuration (new unified approach)
LLM_PROVIDER=openai
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-prod-openai-api-key
LLM_EMBEDDING_MODEL=text-embedding-3-small
LLM_CHAT_MODEL=gpt-4o-mini

# Legacy (still supported)
OPENAI_API_KEY=sk-your-prod-openai-api-key

# QDrant (production)
QDRANT_URL=https://your-qdrant-cluster.qdrant.io
QDRANT_API_KEY=your-production-qdrant-api-key
QDRANT_COLLECTION_NAME=production_documents

# MCP Server (production settings)
MCP_LOG_LEVEL=INFO
MCP_LOG_FILE=/var/log/qdrant-loader/mcp.log
MCP_DISABLE_CONSOLE_LOGGING=true

# Config file substitution variables
STATE_DB_PATH=/var/lib/qdrant-loader/data/qdrant-loader.db
REPO_TOKEN=ghp_your-production-github-token
CONFLUENCE_URL=https://company.atlassian.net
CONFLUENCE_TOKEN=your-confluence-api-token
CONFLUENCE_EMAIL=service-account@company.com
CONFLUENCE_SPACE_KEY=DOCS
JIRA_URL=https://company.atlassian.net
JIRA_TOKEN=your-jira-api-token
JIRA_EMAIL=service-account@company.com
JIRA_PROJECT_KEY=PROJ

# Release automation (if needed)
GITHUB_TOKEN=ghp_your-production-github-token

🔧 Environment Management

Loading Environment Variables

Using .env Files

# Load from .env file
set -a # automatically export all variables
source .env
set +a # stop automatically exporting

# Or use direnv (if installed)
echo "source .env" > .envrc
direnv allow

Using Environment-Specific Files

# Load development environment
source .env.development

# Load production environment
source .env.production

# Load with prefix
env $(xargs < .env.production) qdrant-loader config --workspace .

Validation and Testing

Check Required Variables for MCP Server

# Check if MCP server variables are set (new unified approach)
if [ -z "$LLM_API_KEY" ] && [ -z "$OPENAI_API_KEY" ]; then
  echo "Error: LLM_API_KEY or OPENAI_API_KEY not set (required for MCP server)"
  exit 1
fi

if [ -n "$LLM_API_KEY" ]; then
  echo "✅ LLM_API_KEY is set (new unified approach)"
elif [ -n "$OPENAI_API_KEY" ]; then
  echo "✅ OPENAI_API_KEY is set (legacy support)"
fi

# Optional variables with defaults
echo "QDRANT_URL: ${QDRANT_URL:-http://localhost:6333 (default)}"
echo "QDRANT_COLLECTION_NAME: ${QDRANT_COLLECTION_NAME:-documents (default)}"
echo "MCP_LOG_LEVEL: ${MCP_LOG_LEVEL:-INFO (default)}"

Environment Variable Validation Script

#!/bin/bash
# check-env.sh - Validate environment variables

echo "=== Core Variables (directly used by code) ==="

# Required for MCP server (new unified approach)
if [ -z "$LLM_API_KEY" ] && [ -z "$OPENAI_API_KEY" ]; then
  echo "❌ LLM_API_KEY or OPENAI_API_KEY is not set (required for MCP server)"
  exit 1
fi

if [ -n "$LLM_API_KEY" ]; then
  echo "✅ LLM_API_KEY is set (new unified approach)"
elif [ -n "$OPENAI_API_KEY" ]; then
  echo "✅ OPENAI_API_KEY is set (legacy support)"
fi

# Optional with defaults
echo "✅ QDRANT_URL: ${QDRANT_URL:-http://localhost:6333 (default)}"
echo "✅ QDRANT_COLLECTION_NAME: ${QDRANT_COLLECTION_NAME:-documents (default)}"
echo "✅ MCP_LOG_LEVEL: ${MCP_LOG_LEVEL:-INFO (default)}"

# Optional without defaults
optional_vars=("QDRANT_API_KEY" "CONFLUENCE_TOKEN" "CONFLUENCE_EMAIL" "JIRA_TOKEN" "JIRA_EMAIL" "MCP_LOG_FILE" "MCP_DISABLE_CONSOLE_LOGGING")

echo ""
echo "=== Optional Variables ==="
for var in "${optional_vars[@]}"; do
  if [ -z "${!var}" ]; then
    echo "⚠️ $var is not set (optional)"
  else
    echo "✅ $var is set"
  fi
done

echo ""
echo "Environment validation complete!"

Configuration File Reference - YAML configuration options and substitution
Basic Configuration - Getting started guide
MCP Server Setup - MCP server configuration

📋 Environment Variables Checklist

For MCP Server Usage

[ ] LLM_API_KEY or OPENAI_API_KEY set (required)
[ ] LLM_PROVIDER configured (recommended: openai, ollama, openai_compat)
[ ] LLM_BASE_URL set (required for custom endpoints)
[ ] LLM_EMBEDDING_MODEL set (recommended)
[ ] LLM_CHAT_MODEL set (recommended)
[ ] LLM_VECTOR_SIZE configured (recommended, defaults to 1536)
[ ] QDRANT_URL configured (optional, defaults to localhost)
[ ] QDRANT_COLLECTION_NAME set (optional, defaults to "documents")
[ ] MCP logging variables configured if needed

For QDrant Loader Configuration

[ ] Config file substitution variables set as needed
[ ] Data source credentials configured (Confluence, JIRA, Git)
[ ] Environment file created and secured (chmod 600)
[ ] Variables validated with test commands

Environment configuration complete! 🎉

Your QDrant Loader environment variables are now accurately configured. Remember that most variables are used for config file substitution rather than direct code usage.