Environment Variables

Overview

All command-line parameters can be configured via environment variables. This is particularly useful for:

Storing sensitive credentials (tokens, API keys) outside of configuration files
Container deployments (Docker, Kubernetes)
CI/CD pipelines
Client configurations that support environment variable injection

Command-line parameters take precedence over environment variables when both are specified.

Authentication Variables

These environment variables handle authentication credentials for MotherDuck and cloud storage.

MotherDuck Authentication

motherduck_token

string

MotherDuck access token for authentication.Alternative names: MOTHERDUCK_TOKEN (uppercase version)Command-line equivalent: --motherduck-tokenUsage:

export motherduck_token="your_token_here"
mcp-server-motherduck --db-path md:

In client configuration:

{
  "mcpServers": {
    "MotherDuck": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "your_token_here"
      }
    }
  }
}

For read-only connections, use a read-scaling token. Regular tokens require --read-write mode.

MOTHERDUCK_TOKEN

string

Alternative uppercase version of motherduck_token.Functionally identical to motherduck_token. The server checks for both variables.Usage:

export MOTHERDUCK_TOKEN="your_token_here"
mcp-server-motherduck --db-path md:

AWS Credentials (for S3 Access)

Required when connecting to DuckDB files hosted on Amazon S3.

AWS_ACCESS_KEY_ID

string

AWS access key ID for S3 authentication.Usage:

export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_DEFAULT_REGION="us-west-2"

mcp-server-motherduck --db-path s3://my-bucket/data.duckdb

AWS_SECRET_ACCESS_KEY

string

AWS secret access key for S3 authentication.Used in conjunction with AWS_ACCESS_KEY_ID.

AWS_SESSION_TOKEN

string

AWS session token for temporary credentials.Required when using:

IAM roles
AWS SSO
EC2 instance profiles
Temporary security credentials

Usage:

export AWS_ACCESS_KEY_ID="ASIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_SESSION_TOKEN="FwoGZXIvYXdzEBYaDJ..."
export AWS_DEFAULT_REGION="us-west-2"

mcp-server-motherduck --db-path s3://my-bucket/data.duckdb

AWS_DEFAULT_REGION

string

AWS region for S3 connections.Specifies which AWS region to use when accessing S3-hosted databases.Common values: us-east-1, us-west-2, eu-west-1, ap-southeast-1

MCP Configuration Variables

These environment variables correspond to command-line parameters and control server behavior.

Connection Configuration

MCP_DB_PATH

string

default:":memory:"

Database path (local file, MotherDuck, or S3 URL).Command-line equivalent: --db-pathExamples:

# In-memory database
export MCP_DB_PATH=":memory:"

# Local file
export MCP_DB_PATH="/data/analytics.duckdb"

# MotherDuck
export MCP_DB_PATH="md:production_db"

# S3-hosted database
export MCP_DB_PATH="s3://my-bucket/data.duckdb"

MCP_MOTHERDUCK_CONNECTION_PARAMETERS

string

default:"session_hint=mcp&dbinstance_inactivity_ttl=0s"

Additional MotherDuck connection string parameters.Command-line equivalent: --motherduck-connection-parametersUsage:

export MCP_MOTHERDUCK_CONNECTION_PARAMETERS="session_hint=my_app&dbinstance_inactivity_ttl=1h"

Security Configuration

MCP_READ_WRITE

boolean

default:"false"

Enable write access to the database.Command-line equivalent: --read-writeValues: true, false, 1, 0Usage:

export MCP_READ_WRITE="true"
mcp-server-motherduck --db-path md:

MCP_SAAS_MODE

boolean

default:"false"

Enable MotherDuck SaaS mode (restricts local filesystem access).Command-line equivalent: --motherduck-saas-modeValues: true, false, 1, 0Usage:

export MCP_SAAS_MODE="true"
mcp-server-motherduck --db-path md:

MCP_ALLOW_SWITCH_DATABASES

boolean

default:"false"

Enable the switch_database_connection tool.Command-line equivalent: --allow-switch-databasesValues: true, false, 1, 0Usage:

export MCP_ALLOW_SWITCH_DATABASES="true"

MCP_INIT_SQL

string

SQL file path or SQL string to execute on startup.Command-line equivalent: --init-sqlUsage:

# From file
export MCP_INIT_SQL="/path/to/init.sql"

# SQL string
export MCP_INIT_SQL="INSTALL httpfs; LOAD httpfs;"

Performance Configuration

MCP_MAX_ROWS

integer

default:"1024"

Maximum number of rows to return from queries.Command-line equivalent: --max-rowsUsage:

export MCP_MAX_ROWS="5000"

MCP_MAX_CHARS

integer

default:"50000"

Maximum number of characters in query results.Command-line equivalent: --max-charsUsage:

export MCP_MAX_CHARS="100000"

MCP_QUERY_TIMEOUT

integer

default:"-1"

Query execution timeout in seconds (-1 to disable).Command-line equivalent: --query-timeoutUsage:

export MCP_QUERY_TIMEOUT="30"

MCP_EPHEMERAL_CONNECTIONS

boolean

default:"true"

Use temporary connections for read-only local DuckDB files.Command-line equivalent: --ephemeral-connections / --no-ephemeral-connectionsValues: true, false, 1, 0Usage:

export MCP_EPHEMERAL_CONNECTIONS="false"

Transport Configuration

MCP_TRANSPORT

string

default:"stdio"

Transport type for the MCP server.Command-line equivalent: --transportValues: stdio, http, sse, streamUsage:

export MCP_TRANSPORT="http"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8080"

MCP_STATELESS_HTTP

boolean

default:"false"

Use stateless Streamable HTTP.Command-line equivalent: --stateless-httpValues: true, false, 1, 0Usage:

export MCP_TRANSPORT="http"
export MCP_STATELESS_HTTP="true"

MCP_HOST

string

default:"127.0.0.1"

Host to bind the MCP server (HTTP transport only).Command-line equivalent: --hostUsage:

export MCP_HOST="0.0.0.0"

MCP_PORT

integer

default:"8000"

Port to listen on (HTTP transport only).Command-line equivalent: --portUsage:

export MCP_PORT="8080"

System Configuration

HOME

string

Home directory used by DuckDB for extensions and configuration.Can be overridden with --home-dir command-line parameter.Usage:

export HOME="/custom/home/directory"

Complete Configuration Examples

Example 1: MotherDuck Read-Write via Environment Variables

# Set environment variables
export MCP_DB_PATH="md:production_db"
export motherduck_token="your_token_here"
export MCP_READ_WRITE="true"
export MCP_MAX_ROWS="2048"
export MCP_QUERY_TIMEOUT="30"

# Run server
mcp-server-motherduck

Example 2: S3-Hosted Database with AWS Credentials

# Set AWS credentials
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_DEFAULT_REGION="us-west-2"

# Set MCP configuration
export MCP_DB_PATH="s3://my-data-lake/analytics.duckdb"
export MCP_MAX_ROWS="5000"

# Run server
mcp-server-motherduck

Example 3: Docker Container Configuration

# Dockerfile
FROM python:3.11-slim
RUN pip install mcp-server-motherduck

# Set default environment variables
ENV MCP_DB_PATH=":memory:"
ENV MCP_READ_WRITE="true"
ENV MCP_TRANSPORT="http"
ENV MCP_HOST="0.0.0.0"
ENV MCP_PORT="8000"

CMD ["mcp-server-motherduck"]

# Run container with environment overrides
docker run -p 8000:8000 \
  -e MCP_DB_PATH="md:" \
  -e motherduck_token="your_token" \
  mcp-motherduck

Example 4: Client Configuration with Environment Variables

Claude Desktop / VS Code (config.json):

{
  "mcpServers": {
    "MotherDuck Production": {
      "command": "uvx",
      "args": ["mcp-server-motherduck"],
      "env": {
        "MCP_DB_PATH": "md:production_db",
        "motherduck_token": "your_read_scaling_token",
        "MCP_MAX_ROWS": "2048",
        "MCP_QUERY_TIMEOUT": "30"
      }
    },
    "Local Analytics": {
      "command": "uvx",
      "args": ["mcp-server-motherduck"],
      "env": {
        "MCP_DB_PATH": "/Users/you/data/analytics.duckdb",
        "MCP_READ_WRITE": "true",
        "MCP_EPHEMERAL_CONNECTIONS": "false"
      }
    }
  }
}

Example 5: Kubernetes Deployment with Secrets

apiVersion: v1
kind: Secret
metadata:
  name: motherduck-credentials
type: Opaque
stringData:
  motherduck-token: "your_token_here"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-motherduck
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-motherduck
  template:
    metadata:
      labels:
        app: mcp-motherduck
    spec:
      containers:
      - name: mcp-server
        image: python:3.11-slim
        command: ["sh", "-c", "pip install mcp-server-motherduck && mcp-server-motherduck"]
        env:
        - name: MCP_TRANSPORT
          value: "http"
        - name: MCP_HOST
          value: "0.0.0.0"
        - name: MCP_PORT
          value: "8000"
        - name: MCP_DB_PATH
          value: "md:"
        - name: motherduck_token
          valueFrom:
            secretKeyRef:
              name: motherduck-credentials
              key: motherduck-token
        - name: MCP_MAX_ROWS
          value: "1024"
        - name: MCP_QUERY_TIMEOUT
          value: "30"
        ports:
        - containerPort: 8000

Environment Variable Priority

When the same configuration is specified in multiple places, the following priority order applies (highest to lowest):

Command-line parameters (e.g., --db-path md:)
Environment variables (e.g., MCP_DB_PATH=md:)
Default values (e.g., :memory: for --db-path)

Example:

# Environment variable sets db-path to md:
export MCP_DB_PATH="md:"

# Command-line parameter overrides it to :memory:
mcp-server-motherduck --db-path :memory: --read-write

# Result: Server uses :memory: database

Security Best Practices

Never commit credentials or tokens to version control. Use environment variables, secret managers, or secure configuration files.

Recommendations

Use environment variables for secrets: Store motherduck_token and AWS credentials in environment variables, not in configuration files.
Use secret management tools:
- AWS Secrets Manager / Parameter Store
- HashiCorp Vault
- Kubernetes Secrets
- Docker Secrets
Restrict file permissions: If storing credentials in files, set restrictive permissions:
```
chmod 600 ~/.env
```
Use read-scaling tokens: For read-only MotherDuck access, use read-scaling tokens instead of full access tokens.
Separate environments: Use different tokens/credentials for development, staging, and production.

Example with .env file (not committed to git):

# .env file (add to .gitignore)
motherduck_token="your_token_here"
MCP_DB_PATH="md:production_db"
MCP_MAX_ROWS="2048"

# Load and run
source .env
mcp-server-motherduck

Get Started

Configuration

Guides

Examples

Overview

Authentication Variables

MotherDuck Authentication

AWS Credentials (for S3 Access)

MCP Configuration Variables

Connection Configuration

Security Configuration

Performance Configuration

Transport Configuration

System Configuration

Complete Configuration Examples

Example 1: MotherDuck Read-Write via Environment Variables

Example 2: S3-Hosted Database with AWS Credentials

Example 3: Docker Container Configuration

Example 4: Client Configuration with Environment Variables

Example 5: Kubernetes Deployment with Secrets

Environment Variable Priority

Security Best Practices

Recommendations

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

Examples

​Overview

​Authentication Variables

​MotherDuck Authentication

​AWS Credentials (for S3 Access)

​MCP Configuration Variables

​Connection Configuration

​Security Configuration

​Performance Configuration

​Transport Configuration

​System Configuration

​Complete Configuration Examples

​Example 1: MotherDuck Read-Write via Environment Variables

​Example 2: S3-Hosted Database with AWS Credentials

​Example 3: Docker Container Configuration

​Example 4: Client Configuration with Environment Variables

​Example 5: Kubernetes Deployment with Secrets

​Environment Variable Priority

​Security Best Practices

​Recommendations

Build docs developers (and LLMs) love

Overview

Authentication Variables

MotherDuck Authentication

AWS Credentials (for S3 Access)

MCP Configuration Variables

Connection Configuration

Security Configuration

Performance Configuration

Transport Configuration

System Configuration

Complete Configuration Examples

Example 1: MotherDuck Read-Write via Environment Variables

Example 2: S3-Hosted Database with AWS Credentials

Example 3: Docker Container Configuration

Example 4: Client Configuration with Environment Variables

Example 5: Kubernetes Deployment with Secrets

Environment Variable Priority

Security Best Practices

Recommendations