Skip to main content

Connect to the MotherDuck MCP server

The MotherDuck MCP Server lets AI assistants query and explore your databases using the Model Context Protocol (MCP). This guide walks you through connecting your preferred AI client to the remote MCP server (fully managed, zero setup). For local DuckDB files or self-hosted setups, see the local MCP server.

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. You can also authenticate with an access token instead of OAuth, for example to connect as a service account.

Coding agent with a terminal?

MCP is the right tool for exploring data and answering questions in a chat client. For agents that have a shell and a filesystem, the MotherDuck CLI is more efficient for file-shaped work: reading a Dive or Flight, saving an edit, listing Dives and Flights, and exporting large results, because the output goes to disk instead of through the model's context. See choosing between the CLI and MCP. The two work well together.

Prerequisites​

  • A MotherDuck account (sign up free)
  • An MCP-compatible AI client (Claude, ChatGPT, Cursor, Claude Code, Codex, or others)

Connect with the official MotherDuck plugin​

The official MotherDuck plugin connects ChatGPT and Codex to MotherDuck so you can explore schemas, run queries, and create Dives. It configures the hosted MCP connection for you.

  1. Open Plugins in ChatGPT on the web or in the desktop app.
  2. Search for MotherDuck, open its details, and select + to install it.
  3. Connect your MotherDuck account when prompted.
  4. Start a new ChatGPT or Codex chat. Type @ and select MotherDuck, then ask "List all my databases on MotherDuck."

Confirm that the assistant calls a MotherDuck tool and returns your databases. If installation is unavailable, check your workspace's plugin settings with your administrator. See OpenAI's plugin guide for supported surfaces and access requirements.

Set up the remote MCP server​

Select your MCP client and follow the instructions to connect.

AnthropicAdd MotherDuck to Claude
  1. Open Claude on the web or in Claude Desktop
  2. Go to Customize → Connectors and click + to browse the directory
  3. Find MotherDuck, open its details, and click Connect
  4. Complete the MotherDuck authorization when prompted

After authentication, ask "List all my databases on MotherDuck" to verify the connection. If Claude doesn't use MotherDuck, open + → Connectors in the chat and enable it for that conversation.

On Claude Team and Enterprise plans, an organization owner must enable the connector before members can connect. See Claude's connector guide for organization setup.

Authentication

The remote MCP server uses OAuth, so you sign in with your MotherDuck account during setup. To connect as a service account, or from an agent that can't complete a browser sign-in, use an access token instead. See Connect to the MCP server with an access token.

Offer an MCP connection under your own brand​

If your customers should sign in to your product and access data through tenant service accounts, build a wrapper around the managed remote server. You can select tools, supply business and style guidance, capture question context, and return dashboards in your application. See White-label the MotherDuck MCP server for the architecture and implementation considerations.

Configuring tool permissions​

Most MCP clients let you control how the AI uses each tool. The exact UI varies by client, but the general permission levels are:

PermissionBehavior
Always allowThe AI uses the tool automatically without asking. Faster iteration when errors occur, but no human confirmation before each action.
Needs approvalThe AI asks for your confirmation before each tool use. Gives you visibility into every action.
BlockedThe AI cannot use this tool.
tip

The MCP Server provides both read-only (query) and read-write (query_rw) tools. For exploratory analysis, setting read-only tools to "Always allow" enables faster back-and-forth when the AI needs to retry or refine queries. You can keep query_rw on "Needs approval" or block it if you only need read access. See Restricting to read-only access for more options.

Remote vs local MCP server​

MotherDuck offers two MCP server options:

ServerBest forSetupAccess
Remote (hosted by MotherDuck)Most users who query and modify data on MotherDuck cloudZero setup; connect through URL and OAuthRead-write
Local (mcp-server-motherduck)Self-hosted use; local DuckDB files; or when you need full customizationInstall and run the server yourselfFully customizable

The remote server is recommended for most use cases. Use the local server when you need to work with local DuckDB files, want custom tool configurations, or require full control over the server environment.

Local MCP Server GitHub Repository – Self-host the open-source MCP server for DuckDB and MotherDuck

Where to go from here​