← Back to directory
M

MCP Server Motherduck

Official
SQL analytics and data engineering for AI Assistants and IDEs
GitHub source repository ↗
★ 510 Stars Category · Database Very popular Source revision 275d2e7d2ba4
60FMRS · C
Reliability
7/20
Security and permissions
13/20
Maintenance
12/20
Documentation
15/20
Setup experience
13/20

This MCP server connects AI assistants to DuckDB and MotherDuck, providing powerful SQL analytics. It is flexible, supporting local, in-memory, S3, and cloud databases, with read/write access controlled by flags. The default read-only mode reduces risk, but security configurations must be considered when exposing it to third parties.

Read the FMRS scoring method →

This is a local MCP server that connects AI assistants to DuckDB or MotherDuck databases. It supports querying local DuckDB files, in-memory databases, S3-hosted databases, and MotherDuck. The server allows executing SQL read and write queries, browsing database catalogs, and switching between different database connections on the fly. It runs in read-only mode by default; write access must be explicitly enabled.

Tools

execute_query
Execute SQL query (DuckDB dialect)
list_databases
List all databases
list_tables
List tables and views
list_columns
List columns of a table/view
switch_database_connection
Switch to a different database (requires --allow-switch-databases flag)

Setup

  1. Install uv via pip install uv or brew install uv. 2. Add the JSON configuration to your MCP client's config file, or use client-specific CLI commands as shown in the README. For example, for in-memory DuckDB dev mode: use 'uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases'. 3. For MotherDuck, provide an access token via --motherduck-token or the environment variable motherduck_token.
claude_desktop_config.json
{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:",
        "--read-write",
        "--allow-switch-databases"
      ]
    }
  }
}

Fit and risk

Best for

  • Data scientists and analysts needing SQL analytics on local or remote databases
  • Developers wanting AI-assisted data engineering within IDEs
  • Teams needing to quickly explore DuckDB files
  • Users who want to incorporate MotherDuck cloud capabilities

Not for

  • Users who want a fully managed remote MCP service without local installation
  • Production environments with strict security requirements (default read-only mode still allows local filesystem access)
  • Third-party access without additional security configurations

Required permissions

  • Access to local filesystem (to read DuckDB files or export data)
  • Reads environment variables for MotherDuck tokens and AWS credentials
  • Executes SQL queries in read-only mode by default; write access must be explicitly enabled
  • Optionally switches database connections at runtime (requires --allow-switch-databases)

Risks and side effects

  • If write mode is enabled, data in databases could be modified or deleted
  • By default, when exposed to third parties, local filesystem or sensitive data may be accessed
  • MotherDuck tokens or AWS credentials could be leaked if misconfigured
  • Queries may consume significant resources (memory, CPU) or time out

Troubleshooting

  1. 'spawn uvx ENOENT': specify the full path to uvx (run which uvx to find it)
  2. File locked: ensure --ephemeral-connections is on (default: true) and you are not connected in read-write mode
  3. MotherDuck read-only connections require a read-scaling token; otherwise use --read-write
  4. Ensure the database path is correct (e.g., :memory:, md:, absolute file path, or s3:// URL)

Use cases

Having an AI assistant analyze data from local DuckDB files
Interactive querying and exploration of in-memory DuckDB databases
Combining local data with MotherDuck cloud databases for analysis
Querying DuckDB databases hosted on S3
Using AI for data engineering and prototyping in development environments

Supported clients

Claude DesktopFull support
Claude CodeFull support
Codex CLIFull support
Gemini CLIFull support
CursorFull support
VS CodeFull support
KiroFull support