MotherDuck / DuckDB MCP Server
OfficialQuery local DuckDB files, in-memory DBs, S3, or MotherDuck cloud with read/write SQL.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx mcp-server-motherduck --db-path md: --read-writePaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"motherduck-duckdb-mcp-server": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:"
],
"env": {
"motherduck_token": "<your-motherduck-token>"
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Before you start
- Python with the `uv`/`uvx` package manager installed (`pip install uv` or `brew install uv`)
- A DuckDB target: nothing for `:memory:`, a path to a local `.duckdb` file, an S3 URL, or `md:` for MotherDuck
- For MotherDuck connections: a MotherDuck access token from your MotherDuck account (app.motherduck.com), set as `MOTHERDUCK_TOKEN`
- For S3 access: AWS credentials (access key / secret key, optional session token and region)
About MotherDuck / DuckDB MCP Server
The MotherDuck / DuckDB MCP Server gives AI assistants a full DuckDB SQL engine for analytics and data engineering. It can run queries against an in-memory database, a local .duckdb file, data sitting in S3, or a MotherDuck cloud account — all through the same SQL interface. Because it speaks DuckDB's dialect, it handles CSV/Parquet/JSON files, remote object storage, and cross-database joins natively.
The server runs read-only by default and only allows writes when you pass --read-write, which makes it reasonably safe to point at production data for exploration. It also supports switching the active database connection at runtime (behind the --allow-switch-databases flag), so one server instance can move between local files, S3 paths, and MotherDuck without restarting.
It is the official, MotherDuck-maintained server and is the canonical way to connect Claude, Cursor, VS Code, and other MCP clients to DuckDB-backed data. Distribution is via uvx (no manual clone needed) and it supports both stdio and HTTP transports.
Tools & capabilities (5)
execute_queryRun a SQL query in the DuckDB dialect against the active database (read-only unless --read-write is set)
list_databasesEnumerate all attached/available databases
list_tablesList tables and views, optionally scoped to a database/schema
list_columnsShow the columns of a given table or view
switch_database_connectionChange the active database connection at runtime (requires --allow-switch-databases)
What this server can do
MotherDuck / DuckDB MCP Server provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Use it when you want an AI assistant to explore and query local CSV/Parquet/JSON files via DuckDB SQL
- Use it when you need to run analytical SQL over data in S3 without loading it into a warehouse
- Use it when you want Claude or Cursor to query your MotherDuck cloud database
- Use it when prototyping data pipelines in an in-memory DuckDB you can read and write to
- Use it when you need quick schema discovery (databases, tables, columns) across multiple DuckDB sources
Quick setup
- 1Install `uv` (`pip install uv` or `brew install uv`) so `uvx` is available
- 2Add an `mcpServers` entry to your client running `uvx mcp-server-motherduck` with `--db-path` (e.g. `:memory:`, a file path, an S3 URL, or `md:`)
- 3For MotherDuck, add `MOTHERDUCK_TOKEN` to the config's `env`; for writes add `--read-write`
- 4Optionally add `--allow-switch-databases` to enable runtime connection switching
- 5Restart the MCP client and confirm the DuckDB tools (execute_query, list_tables, etc.) appear
Security notes
The server is read-only by default; only add --read-write when the agent genuinely needs to mutate data. The motherduck_token grants access to your cloud data, so keep it in env vars rather than command-line args.
MotherDuck / DuckDB MCP Server FAQ
Is it read-only by default?
Yes. The server runs in read-only mode unless you explicitly pass the `--read-write` flag, which then permits INSERT/UPDATE/DDL and other write operations.
How do I connect to MotherDuck instead of a local file?
Set `--db-path md:` and provide a `MOTHERDUCK_TOKEN` (env var or `--motherduck-token`). You can get the token from your MotherDuck account settings.
Can it query files in S3?
Yes. Point `--db-path` at an S3 URL (or attach one in SQL) and supply AWS credentials; DuckDB reads Parquet/CSV/JSON directly from the bucket.
Does it support remote/HTTP transport, not just stdio?
Yes. Stdio is the default, but you can pass `--transport http` (with `--host`/`--port`, default 127.0.0.1:8000) to run it as an HTTP server.
Why are my query results truncated?
Results are capped (around 1024 rows / 50,000 characters) to protect the context window; raise the limits with `--max-rows` and `--max-chars`.
Alternatives to MotherDuck / DuckDB MCP Server
Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.
Create, manage, and query your InstantDB apps, schemas, permissions, and data from your AI editor.
