← Explore all mcp servers

LOCAL ANALYTICS / MotherDuck

DuckDB / MotherDuck Local MCP

Executes DuckDB-dialect SQL against a chosen local or remote connection, returning typed-column JSON with truncation markers and a separate database-switching capability.

“Supports connecting to local DuckDB files, in-memory databases, S3-hosted databases, and MotherDuck.”

01 / THE REASONING

Why this made the selection.

  • Separates local files, in-memory, S3 and MotherDuck connection modes, making data location and credential boundaries inspectable.
  • The actual query result includes columns, columnTypes, rows, rowCount and truncation/warning metadata, supporting a more explicit analysis handoff than a bare prose answer.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • README.md, pyproject.toml and LICENSE
  • src/mcp_server_motherduck/__init__.py
  • src/mcp_server_motherduck/server.py
  • src/mcp_server_motherduck/database.py
  • src/mcp_server_motherduck/tools/execute_query.py
  • src/mcp_server_motherduck/tools/switch_database_connection.py

Our findings

  • execute_query takes sql and returns a JSON string containing success, columns, columnTypes, rows and rowCount, adding truncated/warning when capped. Server-level execution errors become raised errors for FastMCP rather than successful result text.
  • Optional switch_database_connection accepts path and create_if_not_exists, validates absolute local paths and existing files, and reports previousDatabase/currentDatabase/readOnly. :memory: is an explicit read-write exception; disabling the switching tool is narrower than trusting its description.
  • A configured timeout uses a timer and conn.interrupt around execution. Row/character caps trim fetched output; execute_raw is a separate uncapped path used by catalog tools. No performance or cancellation behavior was measured.
  • The CLI passes actual_read_only = not read_write, while the Python create_mcp_server function defaults read_only to false. CLI defaults do not automatically apply to library embedding.
  • The manifest names Python >=3.10, duckdb ==1.5.6, fastmcp >=4.0.11, click >=8.5.0, pytz >=2026.5 and hatchling. These are source constraints, not installed/audited versions.
  • This corrects the earlier categorical S3 READ_ONLY statement and narrows the blanket result-limit claim; install/config receipts and the source pin are unchanged.

Not established by this review

  • No MCP server, SQL query, local/remote database connection, extension installation, token use or database switch was executed.
  • No concurrency isolation, S3 fallback success, read-scaling authorization, interrupt behavior, SQL injection test or dependency/security advisory scan. Catalog-tool implementations and external libraries remain outside the reviewed scope.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Connect a server deliberately.

Upstream setup instructions ↗
  1. Use the documented uvx client configuration with an absolute path to an existing DuckDB file.
  2. For MotherDuck, choose the appropriate token type and configure its connection separately; review the production-hardening guidance.
  3. The README gives no standalone install line; its setup is the uvx client configuration and per-client add commands (claude, codex, gemini).

Before you start

  • uv/Python and a DuckDB file, or a MotherDuck account with an appropriate token.

Documented configuration example

Use the client and authentication context described in the setup guidance. Configuration formats vary between hosts.

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

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md

    Supports: upstreamDescription, install, configExample, compatibility, transports, limitations

  2. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/__init__.py

    Supports: review, limitations, access

  3. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/server.py

    Supports: review, summary, whySelected, bestFor, limitations

  4. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/database.py

    Supports: review, limitations, access

  5. Direct SQL handler ↗Checked

    https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/execute_query.py

    Supports: review, limitations

  6. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/switch_database_connection.py

    Supports: review, limitations, access

  7. https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/pyproject.toml

    Supports: review, limitations

  8. Repository licence ↗Checked

    https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/LICENSE

    Supports: license

Evidence & Ask