MotherDuck DuckDB MCP Server

Overview

MotherDuck DuckDB is an MCP server that enables AI assistants and IDEs to interact with DuckDB and MotherDuck databases through SQL queries. It provides a seamless way to analyze data locally or in the cloud without leaving your development environment.

Prerequisites

Before getting started, you'll need:

• uv package manager installed (install via pip install uv or brew install uv)
• For MotherDuck cloud functionality:
  • A MotherDuck account (sign up at app.motherduck.com)
  • An access token generated from the MotherDuck settings page

No special prerequisites are needed for local DuckDB usage, as the MCP server can create an in-memory database on-the-fly or connect to existing database files.

Installation

For Claude Desktop

1. Install Claude Desktop from claude.ai/download
2. Open Claude Desktop and navigate to Settings → Developer → Edit Config
3. Add the MCP server configuration 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"
      ]
    }
  }
}

For Cursor

1. Install Cursor from cursor.com/downloads
2. Open Cursor and go to Settings → MCP → + Add new global MCP server
3. In the mcp.json file that opens, add:

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

For VS Code

1. Press Ctrl + Shift + P and type Preferences: Open User Settings (JSON)
2. Add the following configuration:

{
  "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 create a .vscode/mcp.json file in your workspace with similar configuration to share it with your team.

Configuration Options

The MCP server accepts several configuration options:

• --db-path: Specifies the database path
  • Use md: for MotherDuck cloud database
  • Use a file path for local DuckDB database (e.g., my_database.db)
  • Omit for an in-memory database
• --motherduck-token: Your MotherDuck authentication token (required for cloud functionality)
• --saas-mode: Enable SaaS mode for additional features

Usage Examples

Once installed, you can interact with your database using SQL queries. Here are some examples:

1. Create a table and insert data:

CREATE TABLE users (id INTEGER, name VARCHAR, email VARCHAR);
INSERT INTO users VALUES (1, 'John Doe', 'john@example.com'), (2, 'Jane Smith', 'jane@example.com');

2. Query data:

SELECT * FROM users WHERE id = 1;

3. Load data from a CSV file:

CREATE TABLE sales AS SELECT * FROM read_csv_auto('/path/to/sales.csv');

4. Connect to cloud data in MotherDuck:

SELECT * FROM 'md:my_shared_database.public.customer_data';

Security Considerations

When using the MotherDuck token, be careful not to expose it in shared configurations or public repositories. Consider using environment variables or secure credential storage for production environments.