MotherDuck MCP Server

The MotherDuck MCP Server connects AI assistants such as Claude, Cursor, the Gemini CLI, or GitHub Copilot to MotherDuck, a cloud service for data analytics built on the analytical database DuckDB. Instead of writing SQL queries yourself and copying results by hand, you ask the assistant questions about your tables: it looks at the structure, writes the matching query, runs it, and explains the result. The server is operated by MotherDuck itself; it runs hosted and, according to the documentation, needs no local installation.

What is the MotherDuck MCP Server?

MotherDuck extends DuckDB with storage and compute in the cloud. The MCP server makes these databases accessible to assistants. According to the documentation the endpoint is https://api.motherduck.com/mcp and uses HTTP as its transport. Besides this hosted server there is an open-source repository motherduckdb/mcp-server-motherduck under the MIT license that runs locally and can also query local DuckDB files, in-memory databases, or data in S3. The hosted server, by contrast, cannot reach your local file system.

Which tools are available?

According to the documentation the server offers tools for read-only and for read-write SQL queries, plus tools for listing databases, tables, and columns, searching the catalog, and answering questions about the MotherDuck documentation. The local repository, by contrast, names five tools, including execute_query, list_databases, list_tables, and list_columns; results there are capped at 1,024 rows and 50,000 characters by default so the assistant's context does not overflow.

What is it particularly useful for?

The value lies in exploring unfamiliar data. Anyone taking over a new database can ask the assistant about tables, columns, and typical analyses and gets runnable SQL in the DuckDB dialect that can be checked and reused. Analysts save time on recurring queries, and developers quickly check in the editor what a pipeline has written. Compared with a generic database server, this server knows DuckDB specifics and the structure of the MotherDuck catalog, and its documentation questions can also help with syntax problems.

Setup

For most clients, sign-in works via OAuth in the browser with your own MotherDuck account. Alternatively a MotherDuck access token can be used as a bearer header, for example with the Gemini CLI. The documentation describes steps for Claude, ChatGPT, Cursor, Claude Code, the Gemini CLI, Visual Studio Code with GitHub Copilot, and Copilot Studio. In most cases an entry with the address and the type http in the client configuration is enough.

Requirements, security, and limits

The server requires a MotherDuck account. Because of the write tool you should limit permissions deliberately: the documentation recommends blocking or disabling the write tool, using a service account for shared agents, and applying a read scaling token. The read tool can then safely be set to "always allow", which speeds up exploration. Retrieved data enters the AI client context and therefore reaches the model provider. For the local server the repository stresses that read-only mode alone is not sufficient for access by third parties; for production scenarios the hosted server is recommended.

Costs

The server requires a MotherDuck account. According to the pricing page there is a free Lite plan for individuals and hobby projects, a paid Business plan for production use, and an Enterprise tier by individual agreement. Billing is based on compute, storage and, for the paid plans, a platform fee. Which terms apply to you is shown on the official MotherDuck pricing page.

Who is the MotherDuck MCP Server for?

It is worthwhile for data teams, analysts, and developers who already use DuckDB or MotherDuck and want to do analyses in conversation with an assistant. Anyone working with local files is better served by the open-source local server. Anyone without data in MotherDuck gains nothing from the hosted server: it is an access path to the platform, not a standalone analytics tool.

A MotherDuck account (the free Lite plan is enough to try it out) and an MCP client that supports remote servers, such as Claude, Cursor, or Claude Code.

With the MotherDuck MCP Server, an AI assistant queries your DuckDB databases in the cloud. This guide leads from sign-in to the first query.

Step 1: Check the prerequisites

You need a MotherDuck account and an MCP client that supports remote servers, such as Claude, Cursor, or Claude Code. According to the pricing page the free Lite plan is enough to try it out.

Step 2: Register the server

The endpoint is https://api.motherduck.com/mcp. In Claude Code you register it with claude mcp add --transport http motherduck https://api.motherduck.com/mcp. In other clients an entry with the address and the type http in the configuration is enough.

claude mcp add --transport http motherduck https://api.motherduck.com/mcp

Step 3: Sign in

On first connection the client opens the browser and you confirm access via OAuth with your MotherDuck account. With the Gemini CLI an access token is passed as a header instead; keep it in an environment variable, never in the repository.

Limit write access

The server has a read SQL tool and a write SQL tool. Block the write tool in the client if the assistant should only analyze. For shared agents the documentation recommends a service account and a read scaling token.

Step 4: First queries

Start with questions such as "Which databases and tables exist?" or "Which columns does the orders table have?". Then have analyses written, for example revenue per month. Spot-check the generated SQL.

Step 5: Local server for files

If you want to query local DuckDB files or data in S3, use the open-source repository with uvx mcp-server-motherduck --db-path <path>. Without the --read-write flag access is read-only.

uvx mcp-server-motherduck --db-path <path>

OAuth via the browser with your own MotherDuck account; alternatively a MotherDuck access token as a bearer header.

Read and write SQL access to the databases of the signed-in account; the write tool can be blocked in the client.

The server runs hosted by MotherDuck. Retrieved data enters the AI client context and therefore reaches the model provider.

Unwanted write or delete statements through the write tool, passing business data to the model provider, and an access token stored in the repository.