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.
- 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"
]
}
}
} 04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/README.md
Supports: upstreamDescription, install, configExample, compatibility, transports, limitations
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/__init__.py
Supports: review, limitations, access
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/server.py
Supports: review, summary, whySelected, bestFor, limitations
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/database.py
Supports: review, limitations, access
- Direct SQL handler ↗Checked
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/src/mcp_server_motherduck/tools/execute_query.py
Supports: review, limitations
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 ↗Checked
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/pyproject.toml
Supports: review, limitations
- Repository licence ↗Checked
https://github.com/motherduckdb/mcp-server-motherduck/blob/41acb581d9bc04e427655ba5178b2c5c01f68cd2/LICENSE
Supports: license