MotherDuck MCP server
The official DuckDB / MotherDuck MCP server: run analytical SQL over local DuckDB files, in-memory tables, or a MotherDuck cloud database.
The MotherDuck MCP server connects an agent to DuckDB and MotherDuck so it can run analytical SQL through a single, fast, embedded engine. Point it at an in-memory database, a local .duckdb file, or a MotherDuck cloud database with an md: path, and the agent can list databases, browse tables and their columns, and execute arbitrary DuckDB-dialect queries. Because DuckDB reads Parquet, CSV, and JSON directly and can attach remote object storage, the same server doubles as a way to query data sitting in files or S3 without first loading it into a warehouse.
It is published as the mcp-server-motherduck Python package and is normally launched with uvx (uvx mcp-server-motherduck). The MOTHERDUCK_TOKEN environment variable authenticates against MotherDuck cloud, while --db-path selects the database location and defaults to in-memory. The server is read-only by default; pass --read-write to allow writes, --allow-switch-databases to let the agent change connections, and AWS credentials when you want DuckDB to read directly from S3. Result sets are capped (1024 rows / 50,000 characters by default) so large queries stay agent-friendly, and stdio plus streamable-HTTP transports are both supported.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:"
],
"env": {
"MOTHERDUCK_TOKEN": "<MOTHERDUCK_TOKEN>"
}
}
}
}claude mcp add motherduck -- uvx mcp-server-motherduck --db-path md:Available tools
| Tool | Description |
|---|---|
| execute_query | Executes a SQL query in the DuckDB dialect against the connected DuckDB or MotherDuck database and returns the result rows. |
| list_databases | Lists all databases available on the current connection. |
| list_tables | Lists the tables and views in the connected database. |
| list_columns | Lists the columns (with types) of a specified table or view. |
| switch_database_connection | Switches the active connection to a different database; available only when the server is started with --allow-switch-databases. |
Required configuration
- MOTHERDUCK_TOKENOptional
MotherDuck access token for authenticating against a cloud database. Optional for local/in-memory DuckDB.
- AWS_ACCESS_KEY_IDOptional
AWS access key so DuckDB can read data directly from S3. Optional.
- AWS_SECRET_ACCESS_KEYOptional
AWS secret key paired with AWS_ACCESS_KEY_ID for S3 access. Optional.
What you can do with it
Query data files without a warehouse
Run DuckDB-dialect SQL straight over local Parquet, CSV, or JSON (or S3 objects) so the agent can analyze data files in place, no ETL or warehouse load required.
Cloud analytics over MotherDuck
Connect with a MotherDuck token and an md: path to let the agent explore and query a cloud database, list its tables and columns, and answer analytical questions in seconds.
FAQ
- Is it free?
- The MCP server and DuckDB itself are open source and free. MotherDuck cloud has its own free tier and paid plans; querying local DuckDB files costs nothing.
- Does it support remote/OAuth?
- It runs locally over stdio (via uvx) and can also serve streamable HTTP. It authenticates to MotherDuck cloud with the MOTHERDUCK_TOKEN access token rather than an OAuth flow; local and in-memory databases need no token.