MotherDuck MCP Server

MotherDuck offers a remote MCP server (fully managed, read-only) and a local MCP server (self-hosted, read-write) that let AI assistants query and explore your MotherDuck databases using the Model Context Protocol (MCP). Connect your favorite AI agent to explore schemas, run SQL queries, and ask documentation questions with natural language.

Recommended: Use the remote MCP server for most use cases—zero setup, fully managed, and read-only. Learn about the difference between remote and local, and when to use the local server.

Remote server

Quick Start

Select your MCP client and follow the instructions to connect to the remote MCP server.

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

note

Adding custom MCP connectors in ChatGPT requires a paid plan (Plus, Pro, or Team) to access Developer mode.

If you haven't already, make sure to first turn on 'Developer Mode' on chatgpt.com under Settings → Apps → Advanced

1. Go to ChatGPT Settings → Connectors
2. Click Create App
3. Enter the following:
   • Name: MotherDuck
   • MCP Server URL: https://api.motherduck.com/mcp
4. Click Create and authenticate with your MotherDuck account

Selecting the MotherDuck Connector

Since the MotherDuck connector is currently in Developer mode, you need to explicitly select it to use it in your conversations.

Option 1: Manual selection

Click the + button in the chat input, select More, then choose MotherDuck from the list.

Option 2: Enable automatic connector search

Go to Settings → Personalization, scroll down and enable Connector search. This allows ChatGPT to automatically select the MotherDuck connector when your query is explicit enough about using MotherDuck data.

→ ChatGPT Connectors Documentation

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 supports OAuth authentication. When you add the server to your AI client, you'll be redirected to authenticate with your MotherDuck account. The server uses your MotherDuck credentials to access your databases with the same permissions as your account.

Some clients also support simple authentication - in that case, you can provide your MotherDuck access token as a Bearer header.

Server Capabilities

With the remote MCP server, your agent can:

• Execute read-only SQL queries against your databases
• Explore database schemas, tables, and columns
• Attach and detach shares that have been shared with you
• Ask questions about DuckDB and MotherDuck documentation

Example prompts:

• "Analyze monthly revenue trends and identify our fastest-growing product categories"
• "Compare customer retention rates across different acquisition channels"
• "Build a cohort analysis showing user engagement over their first 90 days"

For clients that support MCP instructions, the remote server provides detailed query guidelines to help AI assistants write effective DuckDB SQL.

Learn more about using the MotherDuck MCP server.

Available Tools

The remote MCP server provides the following tools for AI assistants:

list_databases

List all databases in your MotherDuck account

list_shares

List database shares that have been shared with you

list_tables

List tables and views in a MotherDuck database

list_columns

List columns of a table or view with types and comments

search_catalog

Fuzzy search across databases, schemas, tables, columns, and shares

query

Execute read-only SQL queries against MotherDuck databases

ask_docs_question

Ask questions about DuckDB or MotherDuck documentation

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.

Local server

For local DuckDB databases, write access, or self-hosted scenarios, use the local MCP server—a self-hosted server you run yourself (mcp-server-motherduck).

📦 mcp-server-motherduck – Open-source local MCP server for DuckDB and MotherDuck

The local MCP server supports:

• Read-write operations on local and cloud databases
• Local DuckDB databases (no cloud connection required)
• MotherDuck cloud databases with your access token
• Custom configurations and security settings

Remote vs local

Server	Best for	Setup	Access
Remote (hosted by MotherDuck)	Most users who mainly query data on MotherDuck cloud	Zero setup; connect via URL and OAuth	Read-only
Local (mcp-server-motherduck)	Self-hosted use; local DuckDB files; or when you need write access	Install and run the server yourself	Read-write

• Remote: Fully managed, zero-setup, read-only. Recommended if you mostly query data on MotherDuck cloud. Setup and tools are in the Remote server section above.
• Local: Self-hosted, read-write. Use it when you work mostly with local DuckDB files or need the AI to run write operations. See the Local server section above.

Related Resources

• MCP User Guide - Tips and workflows for using the MotherDuck MCP server
• Building Analytics Agents - Guide to building AI agents with MotherDuck
• MCP Specification (2025-06-18) - Official protocol documentation