@motherduckdb/mcp-server-motherduck

<p align=“center”> <img src=“src/mcp_server_motherduck/assets/duck_feet_square.png” alt=“MotherDuck / DuckDB Local MCP Server” width=“120”> </p>

<h1 align=“center”>DuckDB / MotherDuck Local MCP Server</h1>

<p align=“center”> SQL analytics and data engineering for AI Assistants and IDEs. </p>

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

📝 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	<img src=“https://cursor.com/deeplink/mcp-install-dark.svg” alt=“Install in Cursor” height=“20”>
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.

<details> <summary><b>Claude Code CLI commands</b></summary>

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

</details>

<details> <summary><b>Codex CLI commands</b></summary>

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

</details>

<details> <summary><b>Gemini CLI commands</b></summary>

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

</details>

Tools

*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

Environment Variables

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