MotherDuck MCP Server – DuckDB Analytics for AI
MotherDuck provides managed and local MCP servers that let AI assistants explore schemas, run DuckDB SQL, query MotherDuck databases, and create interactive Dives. Use it when an agent needs governed analytics access to MotherDuck cloud data or a self-hosted DuckDB workflow.
Overview
MotherDuck is a cloud data warehouse built on DuckDB, and its MCP support gives AI assistants a standardized way to work with analytical data. MotherDuck documents two supported MCP options: a fully managed remote server hosted by MotherDuck and a local, self-hosted server for DuckDB and MotherDuck workflows.
What the MCP server enables
The managed remote server connects an MCP-compatible client to MotherDuck so an agent can inspect databases, browse schemas, list tables and columns, search the catalog, run SQL, and ask questions about DuckDB and MotherDuck documentation. It also exposes tools for MotherDuck Dives, including creating, reading, updating, sharing data for, and deleting interactive visualizations stored in a MotherDuck workspace.
The local server is the open-source mcp-server-motherduck implementation. It can connect to local DuckDB files, in-memory DuckDB databases, remote DuckDB files such as S3-backed databases, and MotherDuck cloud databases. It supports SQL analytics and data engineering use cases where the operator wants to run the MCP server locally and control its flags, database path, and security posture.
When to use it
Use the remote server when the data already lives in MotherDuck cloud and the user wants the lowest setup path: connect an MCP client to https://api.motherduck.com/mcp, authenticate with a MotherDuck account, and ask analytical questions in natural language. It is useful for schema discovery, cohort analysis, revenue trend questions, exploratory SQL, and generating shareable Dives from query results.
Use the local server when the workflow depends on a local DuckDB file, in-memory development database, S3-hosted DuckDB file, custom server configuration, or self-hosted security controls. Local mode is also appropriate when teams want to restrict the enabled tools or run the server next to local data.
Connection and authentication
The remote server uses HTTP at https://api.motherduck.com/mcp and supports OAuth authentication through compatible clients. Some clients can also use simple authentication by sending a MotherDuck access token as a Bearer token; using a read-scaling token is the documented way to restrict the remote server to read-only access. The local server runs over stdio with uvx mcp-server-motherduck; MotherDuck cloud access uses the motherduck_token environment variable.
Key considerations
The remote server exposes both read-only query and read-write query_rw tools, so client permission settings and token choice matter. For exploratory analysis, read-only tools can be allowed more freely, while write-capable tools should remain approval-gated or blocked unless intentional. The local server is read-only by default in newer versions; add --read-write only when write access is required. Query results sent through the remote server may transit the MCP server even though MotherDuck states data processing remains in the organization's region, so strict residency requirements should be reviewed before adoption.
Supported Transports
streamable_http
URL: https://api.motherduck.com/mcp
stdio
Command: uvx
Args:
mcp-server-motherduck--db-pathmd:--read-write
Frequently Asked Questions
- When should an AI agent use the MotherDuck MCP Server?
- Use it when an AI assistant needs to analyze data in MotherDuck or DuckDB, inspect schemas, run analytical SQL, answer data questions, or create MotherDuck Dives from query results.
- What does the remote MotherDuck MCP server add to an AI agent?
- The remote server gives the agent managed access to MotherDuck tools for listing databases, exploring tables and columns, searching the catalog, running read-only and read-write SQL, asking DuckDB and MotherDuck documentation questions, and managing Dives.
- What can the local MotherDuck MCP server connect to?
- The local server can connect to in-memory DuckDB databases, local DuckDB files, S3-hosted DuckDB files, and MotherDuck cloud databases. It is intended for self-hosted or customized setups where the operator controls the server flags and runtime environment.
- How is authentication configured for MotherDuck MCP?
- The remote server supports OAuth in compatible clients and can also use a MotherDuck access token as a Bearer token for simple authentication. The local stdio server uses the `motherduck_token` environment variable when connecting to MotherDuck cloud.
- Which MotherDuck MCP transport should be used?
- Use the managed HTTP endpoint for most MotherDuck cloud workflows because it is hosted by MotherDuck and requires minimal setup. Use the local stdio server when working with local DuckDB files, in-memory development databases, S3-hosted DuckDB files, or custom self-hosted security controls.