MotherDuck & DuckDB MCP server

The MotherDuck's DuckDB MCP Server enables AI Assistants and IDEs to interact with DuckDB and MotherDuck databases, providing SQL analytics capabilities through a Model Context Protocol (MCP) implementation. This server allows you to query local or cloud databases, integrate with cloud storage, and perform SQL analytics without complex configuration.

Installation

Prerequisites

• Install uv using pip or Homebrew:

  pip install uv
  # or
  brew install uv
  

• For MotherDuck usage:
  • Sign up for a MotherDuck account
  • Generate an access token via the MotherDuck UI

Setting Up in Cursor

1. Install Cursor from cursor.com/downloads
2. Open Cursor, go to Settings → MCP and click "+ Add new global MCP server"
3. Add this configuration to the opened mcp.json file:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

Setting Up in VS Code

Add the following to your VS Code User Settings (JSON):

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "motherduck_token",
        "description": "MotherDuck Token",
        "password": true
      }
    ],
    "servers": {
      "motherduck": {
        "command": "uvx",
        "args": [
          "mcp-server-motherduck",
          "--db-path",
          "md:",
          "--motherduck-token",
          "${input:motherduck_token}"
        ]
      }
    }
  }
}

Alternatively, create a .vscode/mcp.json file in your workspace with the same configuration.

Setting Up with Claude Desktop

1. Install Claude Desktop from claude.ai/download
2. Open Claude Desktop, go to Settings → Developer → Edit Config
3. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_MOTHERDUCK_TOKEN_HERE>"
      ]
    }
  }
}

Usage

Command Line Parameters

Parameter	Type	Default	Description
--transport	Choice	stdio	Transport type: stdio, sse, or stream
--port	Integer	8000	Port for sse/stream transport modes
--db-path	String	md:	Path to local DuckDB file or MotherDuck database
--motherduck-token	String	None	MotherDuck access token
--read-only	Flag	False	Connect in read-only mode
--home-dir	String	None	Home directory for DuckDB
--saas-mode	Flag	False	Connect to MotherDuck in SaaS mode
--json-response	Flag	False	Enable JSON responses for HTTP stream

Quick Command Examples

# Connect to local DuckDB file in read-only mode
uvx mcp-server-motherduck --transport stream --db-path /path/to/local.db --read-only

# Connect to MotherDuck with token
uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN

# Connect to MotherDuck in SaaS mode for enhanced security
uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN --saas-mode

Connecting to Local DuckDB

To use a local DuckDB database instead of MotherDuck:

In-memory database:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        ":memory:"
      ]
    }
  }
}

Local DuckDB file:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db"
      ]
    }
  }
}

Local DuckDB file in read-only mode:

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "/path/to/your/local.db",
        "--read-only"
      ]
    }
  }
}

Securing Your MCP Server

For enhanced security when exposing your MCP server:

1. Use a read scaling token (restricts write capabilities)
2. Enable SaaS mode to restrict file system access

{
  "mcpServers": {
    "mcp-server-motherduck": {
      "command": "uvx",
      "args": [
        "mcp-server-motherduck",
        "--db-path",
        "md:",
        "--motherduck-token",
        "<YOUR_READ_SCALING_TOKEN_HERE>",
        "--saas-mode"
      ]
    }
  }
}

Running in SSE Mode

Direct SSE mode:

uvx mcp-server-motherduck --transport sse --port 8000 --db-path md: --motherduck-token <your_token>

Using supergateway:

npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_token>"

Example Queries

Once configured, you can ask your AI assistant to:

• Create a new database and table in MotherDuck
• Query data from local CSV files
• Join data from local DuckDB with tables in MotherDuck
• Analyze data stored in Amazon S3

Troubleshooting

• Verify your MotherDuck token is correct if you have connection issues
• Ensure the --home-dir parameter is correctly set for local file access
• Confirm that uvx is in your PATH
• For spawn uvx ENOENT errors, try using the full path to uvx (find with which uvx)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-server-motherduck" '{"command":"uvx","args":["mcp-server-motherduck","--db-path","md:","--motherduck-token","<YOUR_MOTHERDUCK_TOKEN_HERE>"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-server-motherduck": {
            "command": "uvx",
            "args": [
                "mcp-server-motherduck",
                "--db-path",
                "md:",
                "--motherduck-token",
                "<YOUR_MOTHERDUCK_TOKEN_HERE>"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-server-motherduck": {
            "command": "uvx",
            "args": [
                "mcp-server-motherduck",
                "--db-path",
                "md:",
                "--motherduck-token",
                "<YOUR_MOTHERDUCK_TOKEN_HERE>"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect