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).

Prerequisites

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

Set up the remote MCP server

Select your MCP client and follow the instructions to connect.

Claude

Add MotherDuck to Claude

Or manually:

1. Go to Settings → Connectors
2. Click Browse Connectors to find the MotherDuck connector

A browser window should open for authentication. After authentication you can double check the connection by asking "List all my databases on MotherDuck."

ChatGPT

Add MotherDuck to ChatGPT

1. Open the ChatGPT desktop or web app
2. Go to Settings → Apps and click Browse Apps

3. Search for MotherDuck and select it

4. Click Continue to MotherDuck and authenticate with your MotherDuck account

After authentication, ChatGPT can access your MotherDuck data. Try asking "List all my databases on MotherDuck" to verify the connection.

Cursor

Add MotherDuck to Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Tools & MCP
3. Click + New MCP Server
4. Add the following to the configuration file:

{
  "MotherDuck": {
    "url": "https://api.motherduck.com/mcp",
    "type": "http"
  }
}

5. Save and click Connect to authenticate with your MotherDuck account

Cursor MCP Documentation

Claude Code

1. Run the following command in your terminal:

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

tip

By default, this command adds the MCP server to the current project. You can also pass the --scope user flag, and the MCP server will be available for all sessions from your current user (--scope documentation).

2. Run claude to start Claude Code
3. Type /mcp, select MotherDuck from the list, and press Enter
4. Select Authenticate and confirm the authorization dialog

Claude Code MCP Documentation

Others

If you're using Windsurf, Zed, or another MCP-compatible client, use the following JSON configuration:

{
  "mcpServers": {
    "MotherDuck": {
      "url": "https://api.motherduck.com/mcp",
      "type": "http"
    }
  }
}

Authentication

The remote MCP server uses OAuth, so you'll authenticate with your MotherDuck account during setup. Some clients also support token-based authentication through a Bearer header.

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:

Permission	Behavior
Always allow	The AI uses the tool automatically without asking. Faster iteration when errors occur, but no human confirmation before each action.
Needs approval	The AI asks for your confirmation before each tool use. Gives you visibility into every action.
Blocked	The 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:

Server	Best for	Setup	Access
Remote (hosted by MotherDuck)	Most users who query and modify data on MotherDuck cloud	Zero setup; connect through URL and OAuth	Read-write
Local (mcp-server-motherduck)	Self-hosted use; local DuckDB files; or when you need full customization	Install and run the server yourself	Fully 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

• AI Data Analysis Getting Started: 5-minute walkthrough of querying data and creating Dives
• MCP Workflows Guide: Best practices for getting accurate results from AI-powered analysis
• MCP Server Reference: Server capabilities, available tools, and regional availability
• Restricting to Read-Only Access: Restrict your AI assistant to read-only queries