DuckDB and MotherDuck MCP Server Cursor IDE Setup 2026
DuckDB and MotherDuck MCP server Cursor IDE setup 2026: the hosted MotherDuck endpoint at api.motherduck.com/mcp with OAuth or a bearer token, the local mcp-server-motherduck for DuckDB files, S3 and in-memory work, read-only defaults, flags, and the errors you will actually hit.
How do you connect DuckDB or MotherDuck to Cursor over MCP? MotherDuck maintains two servers. If your data lives in MotherDuck's cloud, add the hosted server at https://api.motherduck.com/mcp in Cursor and sign in with OAuth. There is nothing to install. If you want Cursor's agent to query a local .duckdb file, a Parquet folder, an S3-hosted database, or a scratch in-memory database, run the open-source local server with uvx mcp-server-motherduck. The local server opens databases read-only unless you pass --read-write, which is the right default for most analysis work.
This guide covers both options in Cursor desktop, the flags that matter, how to keep the agent from writing to production tables, and the two errors that account for most failed setups. If you are new to the protocol, start with what MCP is and come back.
Which server should you use?
The mcp-server-motherduck README and the MotherDuck MCP docs describe the split the same way: the remote server is hosted and recommended for most MotherDuck users, and the local server is for local DuckDB files, custom configurations, and self-hosting.
| Remote (hosted by MotherDuck) | Local (mcp-server-motherduck) | |
|---|---|---|
| Endpoint | https://api.motherduck.com/mcp | uvx mcp-server-motherduck over stdio |
| Install | None | Python 3.10+ and uv |
| Auth | OAuth in Cursor, or Authorization: Bearer with a MotherDuck token | motherduck_token env var for md:; none for local files |
| Data it reaches | Your MotherDuck databases and shares | Local DuckDB files, :memory:, s3:// databases, MotherDuck |
| Local filesystem | No | Yes: read and write local files, ingest and export |
| Writes | Separate read-only and read-write tools | Read-only unless --read-write |
| Best for | Analysts on MotherDuck, teams, shared tokens | Local files, notebooks, pipelines, offline work |
A quick rule: if the question you want the agent to answer starts with "in our warehouse," use remote. If it starts with "in this file," use local.
Before you start
~/.cursor/mcp.json; project servers in .cursor/mcp.json at the repo root. Our Cursor MCP setup guide covers the basics.uv installed. The README's prerequisite is pip install uv or brew install uv. The PyPI package mcp-server-motherduck requires Python 3.10 or later; uvx downloads and runs it in an isolated environment, so you do not pip install the server yourself./absolute/path/to/your.duckdb. Relative paths resolve against wherever Cursor launched the process, which is rarely your project folder.Option 1: The hosted MotherDuck server
Step 1: Add the server
In Cursor, open Settings > Tools & MCP, choose New MCP Server, and add MotherDuck's documented config:
{
"mcpServers": {
"MotherDuck": {
"url": "https://api.motherduck.com/mcp",
"type": "http"
}
}
}
Save, then select Connect next to the entry. A browser window opens for the MotherDuck sign-in and returns you to Cursor. Once the status turns green, the tools appear in the list.
Step 2 (optional): Use a token instead of OAuth
For a service account, a shared team config, or an environment where browser sign-in isn't possible, MotherDuck documents a bearer-token setup. Keep the token out of the file with Cursor's environment interpolation:
{
"mcpServers": {
"MotherDuck": {
"url": "https://api.motherduck.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MOTHERDUCK_TOKEN}"
}
}
}
}
MotherDuck's docs note that Cursor reads MOTHERDUCK_TOKEN from the environment it starts in. If you launch Cursor from the Dock or Start menu, set the variable in your shell profile or system environment and restart Cursor, or the header goes out empty. The server runs every tool call as the user who owns the token, so a token from a personal admin account gives the agent admin reach.
What the hosted server can do
Per MotherDuck's MCP reference, the hosted server can run read-only and read-write SQL, explore schemas, tables and columns, attach and detach shares, answer questions about DuckDB and MotherDuck documentation, and manage MotherDuck-specific objects: Dives (interactive visualizations), Flights (scheduled Python jobs on MotherDuck compute), and Guides (markdown notes on metric definitions and join conventions that help the agent write correct SQL). Querying is split into a read-only query tool and a read-write query_rw tool.
Query results pass through the remote server. MotherDuck states that your data is processed in your organization's region, and that desktop clients such as Cursor are routed to the MCP server closest to your physical location. If you have strict data-residency rules, read that section of the docs before connecting a production org.
Option 2: The local server for DuckDB files
The local server is the one to use when your data is a file on your laptop, a database in S3, or nothing yet.
A local DuckDB file, read-only
{
"mcpServers": {
"DuckDB (read-only)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", "/Users/you/data/analytics.duckdb"]
}
}
}
No --read-write flag means the agent can query but not modify. The README adds a detail worth knowing: in read-only mode the server doesn't hold the file lock, because --ephemeral-connections (on by default) opens short-lived connections. That lets you keep the file open for writing in a Python script or the DuckDB CLI while Cursor queries it.
In-memory scratch database
{
"mcpServers": {
"DuckDB (in-memory, r/w)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
}
}
}
This is the README's "dev mode." DuckDB can read CSV, Parquet and JSON files directly in SQL, so an in-memory database with read-write access is a quick way to let the agent explore a folder of exports without creating a database file. The README describes this mode as having no guardrails: the agent can write and can switch to any other database at runtime. Keep it for throwaway work.
MotherDuck through the local server
{
"mcpServers": {
"MotherDuck (local, r/w)": {
"command": "uvx",
"args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
"env": {
"motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
}
}
}
}
Use this when you want one server that can join MotherDuck tables with local files. Drop --read-write if the agent only needs to read. The server accepts the token as motherduck_token or MOTHERDUCK_TOKEN, or through --motherduck-token.
A DuckDB file on S3
Pass an s3://bucket/path.duckdb URL as --db-path and set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION (plus AWS_SESSION_TOKEN for temporary credentials) in the env block. The AWS MCP guide covers scoping IAM credentials for agent use.
Local server tools and flags
The local server exposes a small tool set, all returning JSON:
| Tool | What it does |
|---|---|
execute_query | Runs SQL in the DuckDB dialect |
list_databases | Lists attached databases, useful with MotherDuck |
list_tables | Lists tables and views, optionally by database and schema |
list_columns | Lists columns for a table or view |
switch_database_connection | Switches to another database; only with --allow-switch-databases |
Results are capped at 1,024 rows and 50,000 characters by default. Those caps protect Cursor's context window; a 200,000-row result would crowd out your code. Raise them with --max-rows and --max-chars only when you need to, and prefer asking the agent to aggregate.
Flags worth knowing:
--read-write turns on writes. Default is off.--query-timeout <seconds> stops runaway queries. The default is -1, which disables the timeout. Setting 60 or 120 for exploratory work is a reasonable habit.--init-sql runs SQL at startup. The README points to it for applying DuckDB security settings when self-hosting.--motherduck-saas-mode restricts local file access when connected to MotherDuck.--transport http --port 8000 serves Streamable HTTP instead of stdio, for Docker or a shared host. The endpoint is then http://localhost:8000/mcp.Keeping the agent read-only
The defaults help, but be deliberate about it:
1. Local server: leave out --read-write. Don't add --allow-switch-databases unless you need it, since it lets the agent move to a different database mid-session.
2. Hosted server: in Cursor's tool list, disable query_rw or leave it requiring approval. MotherDuck's setup guide recommends the same: allow the read-only query tool freely and keep query_rw on approval or blocked.
3. Tokens: for anything shared, MotherDuck recommends a dedicated service account with a read-scaling token, which can't modify data.
4. Don't treat read-only as a sandbox. The README warns that read-only mode alone is not sufficient when third parties can reach a self-hosted server, because it still allows local filesystem access and changes to DuckDB settings. For third-party access it recommends the hosted server.
Troubleshooting
spawn uvx ENOENT. Cursor can't find uvx because apps launched from the Dock don't inherit your shell PATH. The README's fix: run which uvx and put the full path in "command", for example /Users/you/.local/bin/uvx or /opt/homebrew/bin/uvx.
File locked. Another process holds a write lock on the .duckdb file. Keep --ephemeral-connections on (it is by default) and connect in read-only mode. Two read-write connections to the same file won't work at once.
Remote server connected but empty. If you used the token config, the header may be going out as Bearer with nothing after it. Confirm echo $MOTHERDUCK_TOKEN works in the environment that launched Cursor, then restart Cursor fully.
The agent writes Postgres-flavored SQL. DuckDB's dialect is close to PostgreSQL but not identical. Tell the agent in your prompt or project rules that the database is DuckDB. The hosted server also supplies query guidelines to clients that support MCP instructions.
Results look truncated. That's the 1,024-row default. Ask for aggregates, or raise --max-rows for that server entry.
For anything else, open Cursor's Output panel, pick the MCP log channel, and work through our MCP debugging guide.
DuckDB vs. the other database servers
If your data is already in a warehouse, the vendor's own server usually fits better: see BigQuery, Snowflake or ClickHouse. DuckDB earns its place on files: Parquet exports, CSV dumps, local copies of production tables, and pipelines you want to test before they reach the warehouse. For a transactional app database, the Postgres MCP server is the closer match.
Frequently Asked Questions
Q: Is there an official DuckDB MCP server?
A: MotherDuck, the company behind the MotherDuck cloud service built on DuckDB, maintains the open-source mcp-server-motherduck. Despite the name, it works with plain local DuckDB files, in-memory databases and S3-hosted databases, not only MotherDuck. MotherDuck also runs a hosted MCP server at api.motherduck.com/mcp.
Q: What is the MotherDuck MCP server URL for Cursor?
A: https://api.motherduck.com/mcp with type http. Add it under Settings > Tools & MCP, save, and select Connect to sign in with OAuth. You can use an Authorization: Bearer header with a MotherDuck token instead.
Q: Is the local DuckDB MCP server read-only by default?
A: Yes. The --read-write flag defaults to off, so the server can query but not modify unless you add it. Read-only connections to local files also release the file lock between queries by default.
Q: Why does Cursor say spawn uvx ENOENT?
A: Cursor can't find uvx on its PATH. Run which uvx in a terminal and use that full path as the command in your mcp.json, then restart Cursor.
Q: Can the agent query Parquet or CSV files?
A: Yes, through the local server. DuckDB reads CSV, Parquet and JSON files directly in SQL, so a local or in-memory server can query files by path. The hosted server works with data stored in MotherDuck instead of your local disk.
Related Guides
Sources: motherduckdb/mcp-server-motherduck README, mcp-server-motherduck on PyPI, MotherDuck MCP server reference, Connect to the MotherDuck MCP server, Connect with an access token, Cursor MCP documentation. Checked November 9, 2026.