---
title: "DuckDB / MotherDuck Local MCP: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/mcp-servers/motherduck/
description: "Executes DuckDB-dialect SQL against a chosen local or remote connection, returning typed-column JSON with truncation markers and a separate database-switching capability."
---

# DuckDB / MotherDuck Local MCP: review, setup & limitations · Undominated.ai

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

[← Explore all mcp servers](/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.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/motherduckdb/mcp-server-motherduck)

SOURCE REVIEW

 Reviewed 2026-10-14
 Evidence 8 linked sources
 Publisher MotherDuck
 Licence [MIT ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/LICENSE)
 Revision 41acb581d9bc
 [Read what was—and wasn’t—checked ↓](#review)

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

 [MotherDuck · upstream description ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md) Our analysis follows below.

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.

### A good fit for

 - Inspecting an approved DuckDB dataset with a fixed connection, explicit SQL and a report that retains the query plus truncation status.
- Preparing bounded schema/aggregate evidence for a downstream workbook or research report without mistaking a displayed row window for the whole dataset.

### Weigh up before choosing

 - Read-only is a database connection mode, not a SQL allowlist or filesystem/network sandbox. The execution handler forwards SQL directly; local files, settings and external sources remain relevant.
- With --allow-switch-databases enabled, switching to :memory: forces effective_read_only=false even from a read-only server. Server annotations remain based on the original setting; do not rely on readOnlyHint as enforcement.
- The server shares one DatabaseClient across HTTP requests; --stateless-http does not isolate database selection per caller. Avoid assuming multi-user database/credential isolation.
- Default query output limits are 1024 rows/50,000 characters, not work/cost limits. SQL runs before fetching/trimming output; query timeout defaults to disabled. rowCount counts returned rows, not total matches.
- execute_raw uses fetchall and bypasses the query result caps, so the README's all-tools limit wording is broader than the shared implementation supports. Metadata alone can also exceed the character target after rows are exhausted.
- Local read-only ephemeral connections rerun init SQL on each use. An init SQL file/string can have effects; it is not a harmless one-time declaration.
- MotherDuck read-only requires a read-scaling connection; initial in-memory startup requires --read-write. S3 normally attaches READ_ONLY, but the code includes a missing-database/read-write fallback attempt without that flag.
- The uvx configuration is unversioned. DuckDB, extensions, FastMCP, Click, pytz and transitive dependencies were not installed, licence-audited or advisory-scanned here.

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 ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md)
 - Use the documented uvx client configuration with an absolute path to an existing DuckDB file.
- For MotherDuck, choose the appropriate token type and configure its connection separately; review the production-hardening guidance.
- 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"
 ]
 }
 }
} Copy configuration ↗

### Compatibility

An MCP client supporting stdio or Streamable HTTP; the README gives setup for Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code and Kiro. · uv/Python and a DuckDB file, or a MotherDuck account with an appropriate token.

### Implementation

Python

### Transports

stdio · Streamable HTTP

### Local analytics / Configured credentials or local access

 - Read connected database data and execute arbitrary DuckDB SQL subject to the connection and host controls; --read-write enables ordinary database mutations.
- Queries/init SQL may access files, extensions and external data sources. S3 initialization installs/loads httpfs and consumes configured AWS credentials.
- MotherDuck uses configured tokens; SaaS mode applies to that connection path, not a general local DuckDB sandbox. Optional database switching changes shared server state.

### Cost model

Local compute or MotherDuck query/storage usage determines cost.

04 / FOLLOW THE EVIDENCE

## The source trail.

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

 - [Pinned install/config and deployment cautions ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md Supports: upstreamDescription, install, configExample, compatibility, transports, limitations
- [CLI defaults and HTTP options ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/__init__.py) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/__init__.py Supports: review, limitations, access
- [Server result wrapper and annotations ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/server.py) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/server.py Supports: review, summary, whySelected, bestFor, limitations
- [Actual connection, query and cap behavior ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/database.py) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/database.py Supports: review, limitations, access
- [Direct SQL handler ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/execute_query.py) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/execute_query.py Supports: review, limitations
- [Switch handler and writable-memory exception ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/switch_database_connection.py) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/switch_database_connection.py Supports: review, limitations, access
- [Dependency/build manifest ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/pyproject.toml) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/pyproject.toml Supports: review, limitations
- [Repository licence ↗](https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/LICENSE) Checked 2026-10-14 https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/LICENSE Supports: license

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### AWS IaC MCP Server ↗ Validates CloudFormation templates, retrieves CDK/CloudFormation guidance and investigates failed deployments.](/mcp-servers/aws-iac/)[### AWS Labs OpenAPI MCP ↗ Pins the OpenAPI MCP server that builds tools from an operator-supplied spec and names stdio as the transport.](/mcp-servers/awslabs-openapi/)[### Chroma MCP ↗ Lets an assistant create and query Chroma collections through local, HTTP or Chroma Cloud database connections.](/mcp-servers/chroma/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Inspect resource evidence](/tools/)
- [Choose a host](/agents/)
- [Inspect reusable workflows](/skills/)
- [Use Undominated data](/api/)
