motherduck

---

Connect AI assistants to your data using DuckDB's powerful analytical SQL engine. Supports connecting to local DuckDB files, in-memory databases, S3-hosted databases, and MotherDuck. Allows executing SQL read- and write-queries, browsing database catalogs, and switching between different database connections on-the-fly.

Looking for a fully-managed remote MCP server for MotherDuck? → Go to the MotherDuck Remote MCP docs

Remote vs Local MCP

| | Remote MCP | Local MCP (this repo) | |---|---|---| | Hosting | Hosted by MotherDuck | Runs locally/self-hosted | | Setup | Zero-setup | Requires local installation | | Access | Read-write supported | Read-write supported | | Local filesystem | - | Query across local and remote databases, ingest data from / export data to local filesystem |

📝 Migrating from v0.x?

• Read-only by default: The server now runs in read-only mode by default. Add --read-write to enable write access. See Securing for Production.
• Default database changed: --db-path default changed from md: to :memory:. Add --db-path md: explicitly for MotherDuck.
• MotherDuck read-only requires read-scaling token: MotherDuck connections in read-only mode require a read-scaling token. Regular tokens require --read-write.

Quick Start

Prerequisites: Install uv via pip install uv or brew install uv

Connecting to In-Memory DuckDB (Dev Mode)

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

Full flexibility with no guardrails — read-write access and the ability to switch to any database (local files, S3, or MotherDuck) at runtime.

Connecting to a Local DuckDB File in Read-Only Mode

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

Connects to a specific DuckDB file in read-only mode. Won't hold on to the file lock, so convenient to use alongside a write connection to the same DuckDB file. You can also connect to remote DuckDB files on S3 using s3://bucket/path.duckdb — see Environment Variables for S3 authentication. If you're considering third-party access to the MCP, see Securing for Production.

Connecting to MotherDuck in Read-Write Mode

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

See Command Line Parameters for more options, Securing for Production for deployment guidance, and Troubleshooting if you encounter issues.

Client Setup

| Client | Config Location | One-Click Install | |--------|-----------------|-------------------| | Claude Desktop | Settings → Developer → Edit Config | .mcpb (MCP Bundle) | | Claude Code | Use CLI commands below | - | | Codex CLI | Use CLI commands below or ~/.codex/config.toml | - | | Gemini CLI | Use CLI commands below or ~/.gemini/settings.json | - | | Cursor | Settings → MCP → Add new global MCP server | | | VS Code | Ctrl+Shift+P → "Preferences: Open User Settings (JSON)" | |

Any MCP-compatible client can use this server. Add the JSON configuration from Quick Start to your client's MCP config file. Consult your client's documentation for the config file location.

In-Memory DuckDB (Dev Mode):

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

Local DuckDB (Read-Only):

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

MotherDuck (Read-Write):

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

In-Memory DuckDB (Dev Mode):

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

Local DuckDB (Read-Only):

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

MotherDuck (Read-Write):

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

In-Memory DuckDB (Dev Mode):

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

Local DuckDB (Read-Only):

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

MotherDuck (Read-Write):

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

Tools

| Tool | Description | Required Inputs | Optional Inputs | |------|-------------|-----------------|-----------------| | execute_query | Execute SQL query (DuckDB dialect) | sql | - | | list_databases | List all databases (useful for MotherDuck or multiple attached DBs) | - | - | | list_tables | List tables and views | - | database, schema | | list_columns | List columns of a table/view | table | database, schema | | switch_database_connection* | Switch to different database | path | create_if_not_exists |

*Requires --allow-switch-databases flag

All tools return JSON. Results are limited to 1024 rows / 50,000 chars by default (configurable via --max-rows, --max-chars).

Securing for Production

When giving third parties access to a self-hosted MCP server, read-only mode alone is not sufficient — it still allows access to the local filesystem, changing DuckDB settings, and other potentially sensitive operations.

For production deployments with third-party access, we recommend MotherDuck Remote MCP — zero-setup, read-write capable, and hosted by MotherDuck.

Self-hosting MotherDuck MCP: Fork this repo and customize as needed. Use a service account with read-scaling tokens and enable SaaS mode to restrict local file access.

Self-hosting DuckDB MCP: Use --init-sql to apply security settings. See the Securing DuckDB guide for available options.

Command Line Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | --db-path | :memory: | Database path: local file (absolute), md: (MotherDuck), or s3:// URL | | --motherduck-token | motherduck_token env var | MotherDuck access token | | --read-write | False | Enable write access | | --motherduck-saas-mode | False | MotherDuck SaaS mode (restricts local access) | | --allow-switch-databases | False | Enable switch_database_connection tool | | --max-rows | 1024 | Max rows returned | | --max-chars | 50000 | Max characters returned | | --query-timeout | -1 | Query timeout in seconds (-1 = disabled) | | --init-sql | None | SQL to execute on startup | | --motherduck-connection-parameters | session_hint=mcp&dbinstance_inactivity_ttl=0s | Additional MotherDuck connection string parameters (key=value pairs separated by &) | | --ephemeral-connections | True | Use temporary connections for read-only local files | | --transport | stdio | Transport type: stdio or http | | --stateless-http | False | For protocol compatibility only (e.g. with AWS Bedrock AgentCore Runtime). Server still maintains global state via the shared DatabaseClient. | | --port | 8000 | Port for HTTP transport | | --host | 127.0.0.1 | Host for HTTP transport |

Environment Variables

| Variable | Description | |----------|-------------| | motherduck_token or MOTHERDUCK_TOKEN | MotherDuck access token (alternative to --motherduck-token) | | HOME | Used by DuckDB for extensions and config. Override with --home-dir if not set. | | AWS_ACCESS_KEY_ID | AWS access key for S3 database connections | | AWS_SECRET_ACCESS_KEY | AWS secret key for S3 database connections | | AWS_SESSION_TOKEN | AWS session token for temporary credentials (IAM roles, SSO, EC2 instance profiles) | | AWS_DEFAULT_REGION | AWS region for S3 connections | | AWS_ENDPOINT | AWS endpoint for S3 connections |

Troubleshooting

• spawn uvx ENOENT: Specify full path to uvx (run which uvx to find it)
• File locked: Make sure --ephemeral-connections is turned on (default: true) and that you're not connected in read-write mode

Resources

• MotherDuck MCP Documentation
• Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blog)
• Faster Data Pipelines with MCP and DuckDB (YouTube)

Development

To run from source:

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Release Process

1. Run the Release New Version GitHub Action
2. Enter version in MAJOR.MINOR.PATCH format
3. The workflow bumps version, publishes to PyPI/MCP registry, and creates the GitHub release with MCPB package

License

MIT License - see LICENSE file.

mcp-name: io.github.motherduckdb/mcp-server-motherduck