MotherDuck MCP Server

The MotherDuck MCP server exposes the DuckDB analytical SQL engine to AI assistants. It can query in-memory databases, local .duckdb files, Parquet/CSV/JSON on S3, and MotherDuck cloud databases through a single connection. Agents can list databases, browse tables and columns, and execute SQL using the full DuckDB dialect.

The project ships in two forms. The open-source local server (mcp-server-motherduck on PyPI, run via uvx) is self-hosted and supports stdio or HTTP transport with configurable row, character, and timeout limits. MotherDuck also operates a fully managed remote server at https://api.motherduck.com/mcp that connects via OAuth and adds higher-level capabilities like Dives (interactive visualizations), shares management, and a documentation Q&A tool.

The server is built and maintained by MotherDuck. It defaults to read-only mode for safety, but a --read-write flag enables mutations. Result sets are capped (1024 rows and 50,000 characters by default) to keep responses LLM-friendly, and ephemeral connections are used by default to avoid DuckDB file locks.

Tools

Option A: Remote managed server (recommended)

MotherDuck hosts a remote MCP server at https://api.motherduck.com/mcp that authenticates via OAuth. In clients that support remote MCP (Claude, ChatGPT, Cursor, Windsurf, Zed):

{
  "mcpServers": {
    "MotherDuck": {
      "url": "https://api.motherduck.com/mcp",
      "type": "http"
    }
  }
}

Prerequisites: a MotherDuck account (free tier available). You will be prompted to sign in via browser on first use.

Option B: Local open-source server

Install uv first (pip install uv or brew install uv), then add a server entry. The package is fetched on demand via uvx.

Connect to MotherDuck cloud (read-write):

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Local DuckDB file (read-only):

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

In-memory database:

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Key flags

• --db-path: :memory:, a local file path, md: (MotherDuck), or an S3 URL
• --motherduck-token or motherduck_token env var: MotherDuck auth token
• --read-write: enable mutations (default read-only)
• --allow-switch-databases: permit switch_database_connection tool
• --max-rows (default 1024), --max-chars (default 50000), --query-timeout
• --init-sql: SQL to run on startup
• --transport: stdio (default) or http, with --port and --host
• AWS env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_ENDPOINT) for S3 access

• Ask an agent to profile a local Parquet or CSV dataset by pointing DuckDB at the file and running aggregate queries.
• Query MotherDuck cloud warehouses from Claude or Cursor for ad-hoc analytics without leaving the editor.
• Let an agent explore an unfamiliar schema by listing databases, tables, and columns before writing the actual query.
• Run SQL against datasets on S3 (Parquet, CSV, JSON) using DuckDB's read_parquet/read_csv_auto functions.
• Build and share MotherDuck Dives (visualizations) directly from agent prompts using the remote server.

• "List my MotherDuck databases and show the row counts of the largest five tables."
• "Read the Parquet file at s3://my-bucket/events/2026-05/*.parquet and return daily active users."
• "Connect to my local sales.duckdb and find the top 10 customers by revenue in Q1."
• "What columns are in the orders table, and which ones are nullable?"
• "Create a Dive showing weekly signups by source for the last 90 days and share it with my team."

• Official, maintained by MotherDuck with both a managed remote server and an open-source local server.
• Works against local files, S3, and MotherDuck cloud with a single SQL interface (DuckDB dialect).
• Sensible safety defaults: read-only mode, row/character caps, ephemeral connections to avoid file locks.
• Remote server adds higher-level features (Dives, docs Q&A, catalog search) over the basic SQL tools.

• Write access is off by default and requires --read-write, which complicates agent workflows that mutate data.
• Default response caps (1024 rows, 50,000 chars) can truncate results; large analyses need explicit aggregation.
• MotherDuck warns that read-only mode alone is not sufficient to safely expose the server to untrusted third parties.

• PostgreSQL MCP server for relational Postgres databases.
• ClickHouse MCP server for ClickHouse analytical workloads.
• BigQuery MCP server for Google BigQuery analytics.