Environment Variables

All configuration options can be set via environment variables, which take precedence over configuration files but are overridden by CLI flags.

Naming Convention

Environment variables follow this pattern:

DOCS_MCP_<PATH>

Where <PATH> is the configuration path in UPPER_SNAKE_CASE. Examples:

Config Path	Environment Variable
`scraper.maxPages`	`DOCS_MCP_SCRAPER_MAX_PAGES`
`server.ports.default`	`DOCS_MCP_SERVER_PORTS_DEFAULT`
`app.telemetryEnabled`	`DOCS_MCP_TELEMETRY`
`scraper.document.maxSize`	`DOCS_MCP_SCRAPER_DOCUMENT_MAX_SIZE`

Core Application Variables

General Settings

DOCS_MCP_STORE_PATH

string

Path to data storage directory. Stores SQLite database, embeddings, and cached data.Default:

Linux: ~/.local/share/docs-mcp-server
macOS: ~/Library/Application Support/docs-mcp-server
Windows: %LOCALAPPDATA%\docs-mcp-server

Example:

export DOCS_MCP_STORE_PATH=/mnt/data/docs

DOCS_MCP_CONFIG

string

Path to configuration file (YAML or JSON). When set, the config is read-only.Example:

export DOCS_MCP_CONFIG=/etc/docs-mcp-server/config.yaml

DOCS_MCP_TELEMETRY

boolean

Enable or disable telemetry collection.Default: trueExample:

export DOCS_MCP_TELEMETRY=false

DOCS_MCP_READ_ONLY

boolean

Run in read-only mode (disable write tools and job scheduling).Default: falseExample:

export DOCS_MCP_READ_ONLY=true

DOCS_MCP_EMBEDDING_MODEL

string

Default embedding model in format provider:model-name.Examples:

openai:text-embedding-3-small
vertex:text-embedding-004
bedrock:amazon.titan-embed-text-v1

Example:

export DOCS_MCP_EMBEDDING_MODEL=openai:text-embedding-3-small

Logging

LOG_LEVEL

string

Set log level directly. Overrides --verbose and --silent flags.Values: DEBUG, INFO, WARN, ERRORDefault: INFOExample:

export LOG_LEVEL=DEBUG

Server Configuration

DOCS_MCP_PROTOCOL

string

Server protocol for MCP communication.Values: auto, stdio, httpDefault: autoExample:

export DOCS_MCP_PROTOCOL=http

DOCS_MCP_HOST

string

Host to bind the server to.Default: localhostExample:

export DOCS_MCP_HOST=0.0.0.0

HOST

string

Alternative to DOCS_MCP_HOST. Lower precedence.Example:

export HOST=0.0.0.0

Port Configuration

DOCS_MCP_PORT

number

Default port for all services (unless overridden by specific port variables).Default: 8080Example:

export DOCS_MCP_PORT=3000

PORT

number

Alternative to DOCS_MCP_PORT. Lower precedence (commonly used in hosting platforms).Example:

export PORT=8080

DOCS_MCP_WEB_PORT

number

Port for web interface. Falls back to DOCS_MCP_PORT if not set.Default: 8082Example:

export DOCS_MCP_WEB_PORT=3001

DOCS_MCP_SERVER_PORTS_DEFAULT

number

Explicit default port (highest precedence for default port).Example:

export DOCS_MCP_SERVER_PORTS_DEFAULT=9000

DOCS_MCP_SERVER_PORTS_WORKER

number

Port for pipeline worker service.Example:

export DOCS_MCP_SERVER_PORTS_WORKER=8081

DOCS_MCP_SERVER_PORTS_MCP

number

Port for MCP server.Example:

export DOCS_MCP_SERVER_PORTS_MCP=8082

Authentication

DOCS_MCP_AUTH_ENABLED

boolean

Enable OAuth2/OIDC authentication for MCP endpoints.Default: falseExample:

export DOCS_MCP_AUTH_ENABLED=true

DOCS_MCP_AUTH_ISSUER_URL

string

OAuth2/OIDC issuer URL for authentication.Example:

export DOCS_MCP_AUTH_ISSUER_URL=https://auth.example.com

DOCS_MCP_AUTH_AUDIENCE

string

JWT audience claim (identifies the protected resource).Example:

export DOCS_MCP_AUTH_AUDIENCE=https://api.example.com

Scraper Configuration

DOCS_MCP_SCRAPER_MAX_PAGES

number

Maximum number of pages to scrape per job.Default: 1000Example:

export DOCS_MCP_SCRAPER_MAX_PAGES=2000

DOCS_MCP_SCRAPER_MAX_DEPTH

number

Maximum navigation depth from starting URL.Default: 10Example:

export DOCS_MCP_SCRAPER_MAX_DEPTH=5

DOCS_MCP_SCRAPER_MAX_CONCURRENCY

number

Maximum concurrent page requests.Default: 5Example:

export DOCS_MCP_SCRAPER_MAX_CONCURRENCY=10

DOCS_MCP_SCRAPER_DOCUMENT_MAX_SIZE

number

Maximum document size in bytes. Documents larger than this are rejected.Default: 10485760 (10 MB)Example:

export DOCS_MCP_SCRAPER_DOCUMENT_MAX_SIZE=52428800  # 50 MB

DOCS_MCP_SCRAPER_DOCUMENT_MIN_SIZE

number

Minimum document size in bytes. Documents smaller than this are rejected.Default: 100Example:

export DOCS_MCP_SCRAPER_DOCUMENT_MIN_SIZE=500

Embedding Provider Configuration

Each embedding provider has its own environment variables for authentication.

OpenAI

OPENAI_API_KEY

string

OpenAI API key for embedding generation.Required for: openai:* embedding modelsExample:

export OPENAI_API_KEY=sk-...
export DOCS_MCP_EMBEDDING_MODEL=openai:text-embedding-3-small

OPENAI_API_BASE

string

Custom OpenAI API base URL (for OpenAI-compatible services).Example:

export OPENAI_API_BASE=https://api.custom.com/v1

Google Vertex AI

GOOGLE_APPLICATION_CREDENTIALS

string

Path to Google Cloud service account JSON key file.Required for: vertex:* embedding modelsExample:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export DOCS_MCP_EMBEDDING_MODEL=vertex:text-embedding-004

Google Generative AI

GOOGLE_API_KEY

string

Google API key for Generative AI models.Required for: google:* embedding modelsExample:

export GOOGLE_API_KEY=AIza...
export DOCS_MCP_EMBEDDING_MODEL=google:text-embedding-004

AWS Bedrock

BEDROCK_AWS_REGION

string

AWS region for Bedrock service.Required for: bedrock:* embedding modelsExample:

export BEDROCK_AWS_REGION=us-east-1

AWS_REGION

string

Alternative to BEDROCK_AWS_REGION. Lower precedence.Example:

export AWS_REGION=us-west-2

AWS_PROFILE

string

AWS profile for authentication (uses AWS credentials file).Example:

export AWS_PROFILE=my-profile

AWS_ACCESS_KEY_ID

string

AWS access key ID for direct authentication.Example:

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

AWS_SECRET_ACCESS_KEY

string

AWS secret access key for direct authentication.Example:

export AWS_SECRET_ACCESS_KEY=...

AWS_SESSION_TOKEN

string

AWS session token for temporary credentials.Example:

export AWS_SESSION_TOKEN=...

Azure OpenAI

AZURE_OPENAI_API_KEY

string

Azure OpenAI API key.Required for: azure:* embedding modelsExample:

export AZURE_OPENAI_API_KEY=...

AZURE_OPENAI_API_INSTANCE_NAME

string

Azure OpenAI instance name.Example:

export AZURE_OPENAI_API_INSTANCE_NAME=my-instance

AZURE_OPENAI_API_DEPLOYMENT_NAME

string

Azure OpenAI deployment name.Example:

export AZURE_OPENAI_API_DEPLOYMENT_NAME=text-embedding-ada-002

AZURE_OPENAI_API_VERSION

string

Azure OpenAI API version.Example:

export AZURE_OPENAI_API_VERSION=2023-05-15

Vector Embeddings

DOCS_MCP_EMBEDDINGS_VECTOR_DIMENSION

number

Vector dimension size for embeddings. Must match the embedding model.Common values:

OpenAI text-embedding-3-small: 1536
OpenAI text-embedding-3-large: 3072
Vertex text-embedding-004: 768

Example:

export DOCS_MCP_EMBEDDINGS_VECTOR_DIMENSION=1536

DOCS_MCP_EMBEDDINGS_CHUNK_SIZE

number

Size of text chunks for embedding (in characters).Default: 2000Example:

export DOCS_MCP_EMBEDDINGS_CHUNK_SIZE=1500

DOCS_MCP_EMBEDDINGS_CHUNK_OVERLAP

number

Overlap between consecutive chunks (in characters).Default: 200Example:

export DOCS_MCP_EMBEDDINGS_CHUNK_OVERLAP=100

Configuration Precedence

Settings are applied in this order (highest to lowest priority):

CLI flags (e.g., --max-pages 2000)
Environment variables (e.g., DOCS_MCP_SCRAPER_MAX_PAGES=2000)
Configuration file (e.g., config.yaml)
Built-in defaults

Example:

# config.yaml has: maxPages: 1000
export DOCS_MCP_SCRAPER_MAX_PAGES=1500
docs-mcp-server scrape mylib https://example.com --max-pages 2000
# Result: maxPages = 2000 (CLI flag wins)

# Without CLI flag
docs-mcp-server scrape mylib https://example.com
# Result: maxPages = 1500 (env var wins over config file)

Common Patterns

Development Environment

# .env file for development
DOCS_MCP_STORE_PATH=./data
DOCS_MCP_TELEMETRY=false
LOG_LEVEL=DEBUG
OPENAI_API_KEY=sk-...
DOCS_MCP_EMBEDDING_MODEL=openai:text-embedding-3-small

Production Environment

# Production environment variables
DOCS_MCP_STORE_PATH=/var/lib/docs-mcp-server
DOCS_MCP_CONFIG=/etc/docs-mcp-server/config.yaml
DOCS_MCP_TELEMETRY=true
DOCS_MCP_HOST=0.0.0.0
DOCS_MCP_PORT=8080
DOCS_MCP_AUTH_ENABLED=true
DOCS_MCP_AUTH_ISSUER_URL=https://auth.example.com
DOCS_MCP_AUTH_AUDIENCE=https://api.example.com

Docker Compose

version: '3.8'
services:
  docs-mcp-server:
    image: ghcr.io/arabold/docs-mcp-server
    environment:
      - DOCS_MCP_STORE_PATH=/data
      - DOCS_MCP_PORT=8080
      - DOCS_MCP_HOST=0.0.0.0
      - DOCS_MCP_EMBEDDING_MODEL=openai:text-embedding-3-small
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - DOCS_MCP_TELEMETRY=false
    volumes:
      - ./data:/data
    ports:
      - "8080:8080"

GitHub Actions

env:
  DOCS_MCP_STORE_PATH: ./data
  DOCS_MCP_TELEMETRY: false
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  
steps:
  - name: Scrape documentation
    run: |
      docs-mcp-server scrape mylib https://docs.example.com

Security Best Practices

Protect API Keys

# ❌ Bad: Hardcoded in shell scripts
export OPENAI_API_KEY=sk-1234567890...

# ✅ Good: Load from secure secret management
export OPENAI_API_KEY=$(aws secretsmanager get-secret-value --secret-id openai-key --query SecretString --output text)

# ✅ Good: Use .env file (not committed to git)
source .env

Restrict Permissions

# Ensure .env file is not world-readable
chmod 600 .env

# Ensure store-path is protected
chmod 700 /var/lib/docs-mcp-server

Use Read-Only Mode

# Prevent write operations in production query servers
export DOCS_MCP_READ_ONLY=true

Commands

Options

Naming Convention

Core Application Variables

General Settings

Logging

Server Configuration

Port Configuration

Authentication

Scraper Configuration

Embedding Provider Configuration

OpenAI

Google Vertex AI

Google Generative AI

AWS Bedrock

Azure OpenAI

Vector Embeddings

Configuration Precedence

Common Patterns

Development Environment

Production Environment

Docker Compose

GitHub Actions

Security Best Practices

Protect API Keys

Restrict Permissions

Use Read-Only Mode

See Also

Build docs developers (and LLMs) love

Commands

Options

​Naming Convention

​Core Application Variables

​General Settings

​Logging

​Server Configuration

​Port Configuration

​Authentication

​Scraper Configuration

​Embedding Provider Configuration

​OpenAI

​Google Vertex AI

​Google Generative AI

​AWS Bedrock

​Azure OpenAI

​Vector Embeddings

​Configuration Precedence

​Common Patterns

​Development Environment

​Production Environment

​Docker Compose

​GitHub Actions

​Security Best Practices

​Protect API Keys

​Restrict Permissions

​Use Read-Only Mode

​See Also

Build docs developers (and LLMs) love

Naming Convention

Core Application Variables

General Settings

Logging

Server Configuration

Port Configuration

Authentication

Scraper Configuration

Embedding Provider Configuration

OpenAI

Google Vertex AI

Google Generative AI

AWS Bedrock

Azure OpenAI

Vector Embeddings

Configuration Precedence

Common Patterns

Development Environment

Production Environment

Docker Compose

GitHub Actions

Security Best Practices

Protect API Keys

Restrict Permissions

Use Read-Only Mode

See Also