MotherDuck & DuckDB MCP server

The MotherDuck 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 execute SQL queries directly from compatible tools like Claude or Cursor.

Installation Options

Prerequisites

• uv installed (install via pip install uv or brew install uv)
• For MotherDuck usage: A MotherDuck account and access token from MotherDuck UI
• A compatible MCP client like Claude Desktop, Cursor, or VS Code

Setting Up in Cursor

1. Install Cursor from cursor.com/downloads
2. In Cursor, go to Settings → MCP and click "+ Add new global MCP server"
3. Add the following configuration to the 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 this configuration to your VS Code User Settings (JSON) file (access via Ctrl + Shift + P → Preferences: Open 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, you can add this configuration to .vscode/mcp.json in your workspace.

Setting Up in Claude Desktop

1. Install Claude Desktop from claude.ai/download
2. Open Settings → Developer tab → Edit Config
3. Add the following 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 Guide

Connecting to Databases

MotherDuck Cloud Database

Use the configuration shown above with your MotherDuck token.

Local DuckDB 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"
      ]
    }
  }
}

Read-Only Mode for Local DuckDB

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

Securing Your Server

For enhanced security when exposing the MCP server to third parties:

1. Use a read scaling token (which restricts write capabilities)
2. Enable SaaS mode to restrict access to local files and extensions

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

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 MotherDuck tables
• Analyze data stored in Amazon S3

Manual Testing

You can start the server manually for testing:

# Connect to default MotherDuck database
uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>

# Connect to specific MotherDuck database
uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>

# Connect to local DuckDB database
uvx mcp-server-motherduck --db-path /path/to/your/local.db

# Use in-memory database
uvx mcp-server-motherduck --db-path :memory:

Running in SSE Mode

You can run the server in Server-Sent Events mode using supergateway:

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

Troubleshooting

• Verify your MotherDuck token is correct if you have connection issues
• Ensure uvx is available in your PATH
• For spawn uvx ENOENT errors, try specifying the full path to uvx (output of which uvx)
• Check that any required environment variables are properly set

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.