Skip to main content

​
Overview

MCP Server MotherDuck supports a comprehensive set of command-line parameters that control database connections, security, performance, and transport configuration. All parameters can also be set via environment variables (see Environment Variables).

​
Connection Parameters

These parameters control how the server connects to DuckDB or MotherDuck databases.
​
--db-path
string
default:":memory:"
Path to local DuckDB database file or MotherDuck database.
  • Use :memory: for an in-memory database (requires --read-write flag)
  • Use md: for MotherDuck default database
  • Use md:database_name for a specific MotherDuck database
  • Use absolute file path for local DuckDB files (e.g., /path/to/database.duckdb)
  • Use s3://bucket/path.duckdb for S3-hosted databases
Environment variable: MCP_DB_PATHExamples:
# In-memory database
mcp-server-motherduck --db-path :memory: --read-write

# Local DuckDB file
mcp-server-motherduck --db-path /Users/you/data/analytics.duckdb

# MotherDuck
mcp-server-motherduck --db-path md: --motherduck-token YOUR_TOKEN

# S3-hosted database
mcp-server-motherduck --db-path s3://my-bucket/data.duckdb
​
--motherduck-token
string
default:"None"
Access token to use for MotherDuck database connections.If not specified, the server will look for the token in environment variables motherduck_token or MOTHERDUCK_TOKEN.Environment variables: motherduck_token, MOTHERDUCK_TOKEN
For read-only MotherDuck connections, you need a read-scaling token. Regular tokens require --read-write mode.
Example:
mcp-server-motherduck --db-path md: --motherduck-token abc123xyz456
​
--home-dir
string
default:"None"
Override the home directory for DuckDB. Defaults to system HOME environment variable.DuckDB uses the home directory to store extensions and configuration files. This parameter allows you to override the default location.Example:
mcp-server-motherduck --home-dir /custom/duckdb/home
​
--motherduck-connection-parameters
string
default:"session_hint=mcp&dbinstance_inactivity_ttl=0s"
Additional MotherDuck connection string parameters in key=value format separated by &.These parameters are appended to the MotherDuck connection string and allow fine-tuning of connection behavior.Environment variable: MCP_MOTHERDUCK_CONNECTION_PARAMETERSExample:
# Custom session hint and TTL
mcp-server-motherduck --motherduck-connection-parameters 'session_hint=my_app&dbinstance_inactivity_ttl=1h'

​
Security Parameters

These parameters control access permissions and security settings.
​
--read-write
boolean
default:"false"
Enable write access to the database. By default, the server runs in read-only mode for local DuckDB files and MotherDuck databases.Environment variable: MCP_READ_WRITE
In-memory databases (:memory:) are always writable due to a DuckDB limitation. You must specify --read-write explicitly when using :memory:.
Examples:
# Read-write in-memory database
mcp-server-motherduck --db-path :memory: --read-write

# Read-write MotherDuck connection
mcp-server-motherduck --db-path md: --read-write --motherduck-token YOUR_TOKEN

# Read-only local file (default)
mcp-server-motherduck --db-path /path/to/db.duckdb
​
--motherduck-saas-mode
boolean
default:"false"
Flag for connecting to MotherDuck in SaaS mode.SaaS mode restricts local filesystem access for enhanced security. Recommended for production deployments with third-party access.Environment variable: MCP_SAAS_MODE
See Securing for Production for deployment guidance. Consider using MotherDuck Remote MCP for fully-managed production deployments.
Example:
mcp-server-motherduck --db-path md: --motherduck-saas-mode --motherduck-token YOUR_TOKEN
​
--allow-switch-databases
boolean
default:"false"
Enable the switch_database_connection tool to change databases at runtime.When enabled, AI assistants can switch between different database connections (local files, S3, or MotherDuck) during a session.Environment variable: MCP_ALLOW_SWITCH_DATABASES
Only enable this in trusted environments. It allows AI assistants to connect to any accessible database.
Example:
# Dev mode with full flexibility
mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
​
--init-sql
string
default:"None"
SQL file path or SQL string to execute on startup for database initialization.Useful for applying security settings, creating tables, loading extensions, or setting up the database environment.Environment variable: MCP_INIT_SQLExamples:
# Execute SQL from file
mcp-server-motherduck --init-sql /path/to/init.sql

# Execute SQL string
mcp-server-motherduck --init-sql "INSTALL httpfs; LOAD httpfs;"
For securing DuckDB deployments, see the Securing DuckDB guide.

​
Performance Parameters

These parameters control query execution and result limits.
​
--max-rows
integer
default:"1024"
Maximum number of rows to return from queries.Use SQL LIMIT clauses in your queries for specific row counts. This parameter provides a global limit to prevent overwhelming responses.Environment variable: MCP_MAX_ROWSExample:
mcp-server-motherduck --max-rows 5000
​
--max-chars
integer
default:"50000"
Maximum number of characters in query results.Prevents issues with wide rows or large text columns by truncating results if they exceed this limit.Environment variable: MCP_MAX_CHARSExample:
mcp-server-motherduck --max-chars 100000
​
--query-timeout
integer
default:"-1"
Query execution timeout in seconds. Set to -1 to disable timeout.Environment variable: MCP_QUERY_TIMEOUTExamples:
# 30 second timeout
mcp-server-motherduck --query-timeout 30

# Disable timeout
mcp-server-motherduck --query-timeout -1
​
--ephemeral-connections
boolean
default:"true"
Use temporary connections for read-only local DuckDB files.When enabled, the server creates a new connection for each query, keeping the file unlocked so other processes can write to it. Use --no-ephemeral-connections to maintain a persistent connection.Environment variable: MCP_EPHEMERAL_CONNECTIONSExamples:
# Ephemeral connections (default)
mcp-server-motherduck --db-path /path/to/db.duckdb

# Persistent connection
mcp-server-motherduck --db-path /path/to/db.duckdb --no-ephemeral-connections
Ephemeral connections are only used for read-only local DuckDB files. They have no effect on in-memory databases or MotherDuck connections.

​
Transport Parameters

These parameters control how the MCP server communicates with clients.
​
--transport
choice
default:"stdio"
Transport type for the MCP server.Choices: stdio, http, sse, stream
  • stdio: Standard input/output (default, for local AI assistants)
  • http: Streamable HTTP transport (for remote connections)
  • sse, stream: Deprecated aliases for http
Environment variable: MCP_TRANSPORT
sse and stream are deprecated. Use http instead.
Examples:
# stdio transport (default)
mcp-server-motherduck --transport stdio

# HTTP transport
mcp-server-motherduck --transport http --host 0.0.0.0 --port 8080
​
--stateless-http
boolean
default:"false"
Use stateless Streamable HTTP when --transport http.Required for platforms that inject Mcp-Session-Id headers (e.g., AWS Bedrock AgentCore Runtime).Environment variable: MCP_STATELESS_HTTP
This is for protocol compatibility only. The server still maintains global state via the shared DatabaseClient.
Example:
mcp-server-motherduck --transport http --stateless-http
​
--host
string
default:"127.0.0.1"
Host to bind the MCP server when using HTTP transport.Environment variable: MCP_HOSTExamples:
# Localhost only (default)
mcp-server-motherduck --transport http --host 127.0.0.1

# All interfaces
mcp-server-motherduck --transport http --host 0.0.0.0
​
--port
integer
default:"8000"
Port to listen on for HTTP transport.Environment variable: MCP_PORTExample:
mcp-server-motherduck --transport http --port 8080

​
Complete Configuration Examples

​
Development: In-Memory with Full Access

mcp-server-motherduck \
  --db-path :memory: \
  --read-write \
  --allow-switch-databases \
  --max-rows 5000 \
  --query-timeout 60

​
Production: MotherDuck Read-Only with SaaS Mode

mcp-server-motherduck \
  --db-path md:production_db \
  --motherduck-token YOUR_READ_SCALING_TOKEN \
  --motherduck-saas-mode \
  --max-rows 1024 \
  --query-timeout 30

​
Local File: Read-Write with Initialization

mcp-server-motherduck \
  --db-path /data/analytics.duckdb \
  --read-write \
  --init-sql "INSTALL httpfs; LOAD httpfs; INSTALL spatial; LOAD spatial;" \
  --ephemeral-connections false \
  --max-rows 2048

​
HTTP Transport: Remote Access

mcp-server-motherduck \
  --transport http \
  --host 0.0.0.0 \
  --port 8080 \
  --db-path md: \
  --motherduck-token YOUR_TOKEN \
  --read-write

​
Deprecated Parameters

The following parameters are deprecated and should not be used:
  • --saas-mode: Use --motherduck-saas-mode instead
  • --read-only: Read-only is now the default. Use --read-write for write access
  • --json-response: No longer needed, JSON responses are automatic
Using deprecated parameters will generate warnings but the server will still run. Update your configuration to use the new parameters.

Build docs developers (and LLMs) love

Get started for freeTalk to us