Title: MCP Server | MotherDuck Docs
URL Source: https://motherduck.com/docs/sql-reference/mcp/
Markdown Content:
MotherDuck offers a remote MCP server (fully managed, read-write) and a local MCP server (fully customizable, self-hosted) that let AI assistants query and explore your MotherDuck databases using the Model Context Protocol (MCP).
Connection URL
The remote MCP server is hosted at https://api.motherduck.com/mcp. Most clients connect through OAuth automatically; clients that need a manual configuration use this URL with an HTTP transport.
For step-by-step setup instructions for all supported clients (Claude, ChatGPT, Cursor, Claude Code, and others), see Connect to the MotherDuck MCP Server.
note
Every tool result the MCP server returns passes through the model's context. For agents that have a shell, the MotherDuck CLI handles file-shaped work with fewer tokens: pulling and pushing a Dive or a Flight, listing Dives and Flights, and exporting large results all go through files and stdout instead. See choosing between the CLI and MCP.
Server capabilities
With the remote MCP server, your agent can:
- Execute read-only and read-write SQL against your databases
- Explore database schemas, tables, and columns
- Attach and detach shares
- Ask questions about DuckDB and MotherDuck documentation
- Create and manage Dives (interactive data visualizations)
- Render Dives inline in supported clients with the Dive Viewer MCP App, so you iterate against live data instead of a sample-data preview
- Create, schedule, run, and monitor Flights (scheduled Python jobs on MotherDuck compute)
- Read and write Guides — markdown documents that capture your org's metric definitions, join conventions, and domain context, so agents produce accurate SQL without repetitive prompting
For clients that support MCP instructions, the remote MCP server provides detailed query guidelines to help AI assistants write effective DuckDB SQL. Learn more about using the MotherDuck MCP server.
Regional availability
The remote MCP server is available in all MotherDuck regions. Requests are routed to the MCP server closest to where the client runs:
- Desktop clients (Cursor, Claude Code): Routed based on your physical location
- Web-based agents (Claude.ai, ChatGPT): Routed based on the agent provider's server location
Your data is always processed in your MotherDuck organization's region. However, query results transit through the remote MCP server. If you have strict data residency requirements, ensure your MCP client runs within your region.
Restricting to read-only access
The remote MCP server exposes both read-only and read-write tools. To restrict your AI assistant to read-only access, see Restricting to read-only access.
White-labeling and backend authentication
Backend MCP clients can authenticate to https://api.motherduck.com/mcp with an Authorization: Bearer <motherduck_token> header. A wrapper can select a service-account token for each authenticated tenant and expose a curated set of tools under your product's name. See White-label the MotherDuck MCP server for authentication, Guides, question capture, and Dive integration.
Tool reference
The remote MCP server's tools are grouped by what they operate on: core tools for querying databases, exploring schemas and shares, and asking documentation questions; Dive tools for creating and managing Dives; Flight tools for creating, scheduling, and monitoring Flights; and Guide tools for creating and managing Guides.