Verified MCP server: DuckDB
The short answer
Last verified 2026-08-03
The DuckDB MCP server lets an AI assistant run SQL against a DuckDB database file that sits on your own Mac. The package is mcp-server-motherduck, published by MotherDuck, the company behind the hosted DuckDB service, and it starts with uvx, so what actually runs is a small Python program talking to your AI app over stdio. Pointed at a database file it asks for no account, no API key and no token; a MotherDuck token matters only for the md: cloud mode, and the exact error a wrong one returns is printed further down this page. We did not take the README's word for any of that: we ran the server, spoke the protocol to it, enumerated all four tools, ran a real query that came back with a row, and kept the raw output, including the errors it returns when something goes wrong. All of it is on this page. [1][3][5]
Verification
Method
We spawned the server with uvx over stdio, pointed at a throwaway DuckDB file with --db-path and --read-write, completed the MCP initialize handshake, called tools/list, and ran one real tool call: execute_query with the SQL SELECT 42 AS answer, which came back with a row. No credential of any kind was set, because a database file on your own Mac needs none. The raw JSON was captured on the wire, and the tool table below is that capture, word for word. This Mac ran uvx 0.10.2; the Node version in the strip above belongs to our test client, because the server itself is Python and does not need Node. Four more sessions were run on purpose to break things, and every error they returned is printed further down.
Startup banner
[motherduck] INFO - 🦆 MotherDuck MCP Server v1.0.7
[motherduck] INFO - Ready to execute SQL queries via DuckDB/MotherDuck
[motherduck] INFO - Database mode: read-write
[motherduck] INFO - Query result limits: 1024 rows, 50,000 characters
[motherduck] INFO - Query timeout: disabled
[motherduck] INFO - Database client initialized in `duckdb` mode
[motherduck] INFO - FastMCP server created
[motherduck] INFO - MCP server initialized in [32mstdio[0m mode
[motherduck] INFO - Waiting for client connection
╭──────────────────────────────────────────────────────────────────────────────╮
│ │
│ │
│ ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█ │
│ █▀ █▀█ ▄▄█ █ █ ▀ █ █▄▄ █▀▀ │
│ │
│ │
│ │
│ FastMCP 3.4.5 │
│ https://gofastmcp.com │
│ │
│ 🖥 Server: mcp-server-motherduck, 1.0.7 │
│ 🚀 Deploy free: https://horizon.prefect.io │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
[08/03/26 23:58:50] INFO Starting MCP server transport.py:241
'mcp-server-motherduck' with
transport 'stdio'
[motherduck] INFO - Processing request of type ListToolsRequest
[motherduck] INFO - Processing request of type CallToolRequest
[motherduck] INFO - 🔌 Connecting to duckdb database
[motherduck] INFO - ✅ Successfully connected to duckdb database
One real tool call
tools/call execute_query {"sql": "SELECT 42 AS answer"}{
"success": true,
"columns": [
"answer"
],
"columnTypes": [
"INTEGER"
],
"rows": [
[
42
]
],
"rowCount": 1
}Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 4 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| execute_querysql* | Execute a SQL query on the DuckDB or MotherDuck database. Unqualified table names resolve to current_database() and current_schema() automatically. Fully qualified names (database.schema.table) are only needed when multiple DuckDB databases are attached or when connected to MotherDuck. |
| list_databases | List all databases available in the connection. Useful when multiple DuckDB databases are attached or when connected to MotherDuck. |
| list_tablesdatabaseschema | List all tables and views in a database with their comments. If database is not specified, uses the current database. |
| list_columnstable*databaseschema | List all columns of a table or view with their types and comments. If database/schema are not specified, uses the current database/schema. |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"duckdb": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/Users/yourname/Documents/analytics.duckdb",
"--read-write"
]
}
}
}Replace the database path with the full path of a DuckDB file of your own, then quit and reopen Claude Desktop. The file itself does not have to exist yet, but the folder around it does. Drop the --read-write line to keep the assistant read-only, which is what the server does when the flag is absent. For MotherDuck cloud instead of a file, put "md:" in place of the path and add "--motherduck-token", "YOUR_MOTHERDUCK_TOKEN" to the same list. [3][6]
One command in your terminal:
claude mcp add --transport stdio duckdb -- uvx mcp-server-motherduck --db-path /Users/yourname/Documents/analytics.duckdb --read-write
Everything after the double dash is the exact command Claude Code will run, so swap the path for a DuckDB file of your own. For MotherDuck cloud instead, put --env motherduck_token=YOUR_MOTHERDUCK_TOKEN before the double dash and use --db-path md: in place of the file path. [7][3]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"duckdb": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/Users/yourname/Documents/analytics.duckdb",
"--read-write"
]
}
}
}Cursor picks the file up on restart. If you switch this to MotherDuck cloud and paste a token into it, keep the whole block in the personal file at ~/.cursor/mcp.json, because a project file is shared with everyone who has the repository. [8][3]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name DuckDB Command uvx Arguments mcp-server-motherduck --db-path /Users/yourname/Documents/analytics.duckdb --read-write
The Arguments field splits on spaces, so use a full database path with no spaces in it, starting with /Users. Leave Environment Variables empty for a file on your Mac; only MotherDuck cloud needs a row there, motherduck_token with your token in it. Click Test Connection first: a working server answers with its tool count, four for this one. [9][3]
No terminal needed
If you have never opened Terminal and would rather keep it that way, this is nearly your path: one install stands in the way, and after it there is nothing to type. Routines is a Mac app that runs MCP servers for you: fill in three fields once, and this server's tools are available to your AI in chat and in scheduled routines.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in. This server is a Python package, so it also needs uv, the tool that provides the uvx command. Install it from astral.sh/uv, or with one terminal line if you already use Homebrew: brew install uv.
02
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
03
Switch the form to Command (stdio): this server is a command that runs on your Mac, not a web address. Name: DuckDB. Command: uvx.
04
Arguments: mcp-server-motherduck --db-path followed by a space and the full path of your DuckDB file, like /Users/yourname/Documents/analytics.duckdb, and then --read-write if the assistant should be allowed to create and change tables. Write the path in full, starting with /Users, with no spaces in it. The file does not have to exist yet, but the folder around it does.
05
Leave Environment Variables empty: a database file on your Mac needs no credential, and that is the part this page proves rather than repeats. The one exception is MotherDuck cloud, which wants a single row here, motherduck_token. Click Test Connection: Routines starts the server and reports how many tools it found, four for this one. Then click Add Server.
06
The tools work in chat right away: ask your question in plain words and let the assistant write the SQL. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every Monday at 8:00, query my DuckDB database for last week's orders and write me a short summary with the total revenue, the number of orders, the five best selling products, and how each number compares with the week before.
Every weekday at 7:30, check my DuckDB database for rows that look wrong: customers with no email address, orders with no customer, and prices below zero. List what you find with a count for each problem, and say nothing if everything is clean.
Every Friday at 17:00, list the tables in my DuckDB database with their row counts, point out any table or column that was not there last week, and give me the whole thing as a one-page summary I can skim.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
1 validation error for call[execute_query]
sql
Missing required argument [type=missing_argument, input_value={}, input_type=dict]
For further information visit https://errors.pydantic.dev/2.13/v/missing_argumentThe fix
The argument is called sql, not query, a mistake we made ourselves on the first attempt of the run this page is dated by. The message above is what the server returns when the sql argument is missing entirely, captured in a probe session we ran on purpose. An assistant normally reads the right name off the tool schema, so this is the error you hit when you drive the server from your own script: send {"sql": "SELECT 1"} and it works.
What you see
Error calling tool 'execute_query': {
"success": false,
"error": "Parser Error: syntax error at or near \"SELEKT\"\n\nLINE 1: SELEKT this is not valid sql\n ^",
"errorType": "ParserException"
}The fix
A real DuckDB parser error, passed straight through to the assistant. We triggered this one on purpose by writing SELEKT instead of SELECT, and the caret in the message points at the word the database choked on. In practice most of these are a table or column spelled differently than expected, so ask the assistant to run list_tables and list_columns before it guesses at names.
What you see
Unknown tool: 'execute_qeury'
The fix
The tool name was misspelled, ours deliberately. This server answers to exactly four names, execute_query, list_databases, list_tables and list_columns, and anything else comes back like this with no further explanation. Copy the name out of the table on this page.
What you see
Error calling tool 'execute_query': {
"success": false,
"error": "Invalid Input Error: Initialization function \"motherduck_duckdb_cpp_init\" from file \"/Users/[REDACTED]/.duckdb/extensions/v1.5.3/osx_amd64/motherduck.duckdb_extension\" threw an exception: \"Invalid Error: Request failed: Your request is not authenticated. Please check your MotherDuck token. (Jwt is not in the form of Header.Payload.Signature with two dots and 3 sections, request id: '819fc96d-2d4a-4040-a6c7-f9f492433eb3')\"",
"errorType": "InvalidInputException"
}The fix
This is the md: cloud path, not the file path. The server takes the token without checking it at startup, so the handshake and the tool list both succeed and the failure only lands on the first query that touches MotherDuck, which makes the connection look healthy until you ask something. The line about Jwt not being in the form of Header.Payload.Signature means the value is not a MotherDuck token at all, which is exactly what we sent: a placeholder string. Paste a real token from your MotherDuck account, or leave the cloud out of it and point --db-path at a file on your Mac, which needs no token. The home directory in the path above is redacted; nothing else in the message is edited.
What you see
Error calling tool 'execute_query': {
"success": false,
"error": "IO Error: Cannot open file \"/definitely/not/a/real/directory/nope.duckdb\": No such file or directory",
"errorType": "IOException"
}The fix
The database file does not have to exist, but the folder around it does. We pointed --db-path into a folder that is not there, and once again the server started and listed its tools normally, because it only opens the database when a query arrives. Correct the path or create the folder first, and write the path in full starting with /Users rather than with a ~ shortcut.
The fix
The uvx command belongs to uv, the Python package runner. If uv is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install it from astral.sh/uv, then run which uvx in a terminal: if it prints a path but a Mac app still cannot start the server, paste that full path into the command field, because an app launched from the Dock does not always inherit your shell PATH.
FAQ
It is a small program that connects an AI assistant such as Claude to DuckDB, the analytics database that lives in a single file. Once connected, you ask a question in plain English, the assistant writes the SQL, the server runs it and hands the rows back. The package is mcp-server-motherduck, published by MotherDuck, and it runs as a local process on your Mac that talks to your AI app over stdio. The same server also reaches MotherDuck cloud databases, which is the only mode that needs a token. [3][1]
Four, and we counted them live: execute_query, which takes one sql parameter and runs it, plus list_databases, list_tables and list_columns for looking around before writing a query. The table above is the live tools/list output, word for word. Nearly everything happens through execute_query, so what the assistant knows about SQL matters more here than the length of the tool list does.
It is read-only until you ask for more. The --read-write flag is what unlocks writing, and the server prints its own database mode on startup: read-write on our main run, which used the flag, and read-only on the probe that left it off. In read-write mode execute_query can create, change and drop tables, which is why the server labels that tool as destructive when it describes itself to the assistant. The real risk is scope, because one tool that accepts any SQL sees everything inside the file you point it at. Point it at a copy rather than at the only version of anything you care about, and leave --read-write off until a task genuinely needs it.
Not for a database file on your Mac. There is nothing to sign up for and no credential to paste, which is why the sample call on this page came back with real rows instead of an authentication error. A MotherDuck token is needed only if you point --db-path at md:, the hosted cloud mode, and the error a wrong one returns is printed in the troubleshooting section above. The uvx command downloads the package from the public PyPI registry on first run, so the very first start needs an internet connection; after that it is cached on your Mac. [1]
Once, to install uv, the tool that provides the uvx command, because this server is a Python package. After that, no: in Routines you fill three fields in Settings and click Test Connection, and the walkthrough above shows every click. Claude Desktop and Cursor each need a small JSON file edited once. Only Claude Code is terminal-first by nature. [9][6]
Because MotherDuck, the company that runs a hosted DuckDB service, publishes it, and one package covers both cases: a DuckDB file on your disk and their cloud. PulseMCP lists it as the official MotherDuck and DuckDB MCP server, the repository sits in the motherduckdb organization on GitHub with 506 stars and an MIT license, and it was last pushed on 2026-07-27. Nothing about the file mode reaches MotherDuck: our verification run used a plain file on the Mac and set no token at all. [5][3][4]
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs. One detail sets it apart from most servers in this directory: it ships on PyPI, so the command is uvx everywhere and never npx. [6][7][8][9][1]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 1.0.7, published 2026-06-09. Requires Python 3.10 or newer. Published to PyPI, with no npm package of this name.
[2]
9,555 downloads in the last seven days at access time, and 43,674 in the last thirty.
[3]
506 stars, an MIT license, not archived, and a push dated 2026-07-27 per the GitHub API. Its README publishes the uvx command, the JSON config block and the stdio transport.
[4]
MotherDuck Corporation, the company behind the hosted DuckDB service, owns the package.
[5]
Lists this package as the official MotherDuck and DuckDB MCP server.
[6]
Where the Claude Desktop config file lives and the mcpServers command and args shape.
[7]
The claude mcp add [options] <name> -- <command> [args...] syntax, including --transport and --env.
[8]
[9]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes DuckDB as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines