📌Overview

Purpose: To provide a seamless integration of MotherDuck and local DuckDB for enhanced SQL analytics capabilities.

Overview: The MotherDuck MCP Server combines cloud-based SQL analytics from MotherDuck with local DuckDB, offering users the ability to execute SQL queries across both environments efficiently.

Key Features:

• Hybrid execution: Allows querying data from both MotherDuck and local DuckDB, enabling flexibility in data management.

• Cloud storage integration: Grants access to data stored in services like Amazon S3, streamlining data retrieval processes.

• Data sharing: Facilitates the creation and sharing of databases, enhancing collaboration capabilities.

• SQL analytics: Leverages DuckDB's SQL dialect for querying data, accommodating large datasets directly from the user interface.

• Serverless architecture: Operates without the need for manual configuration of instances or clusters, simplifying the user experience.

---

MotherDuck MCP Server

An MCP server implementation that integrates MotherDuck and local DuckDB, providing SQL analytics capabilities to Claude.

Features

• Hybrid execution: Query data from both cloud-based MotherDuck and local DuckDB.
• Cloud storage integration: Access data stored in Amazon S3 and other cloud storage.
• Data sharing: Create and share databases.
• SQL analytics: Use DuckDB's SQL dialect to query data directly from Claude.
• Serverless architecture: Run analytics without configuring instances or clusters.

Components

Prompts

• duckdb-motherduck-initial-prompt: Initializes a connection to DuckDB or MotherDuck.

Tools

• query: Executes a SQL query on the MotherDuck/DuckDB database.
  • Inputs:
    • query (string, required): The SQL query to execute.

Getting Started

Prerequisites

• A MotherDuck account.
• A MotherDuck access token.
• uv installed (pip install uv or brew install uv).

If using with Claude Desktop, ensure it is installed.

Setting up your MotherDuck token

1. Sign up for a MotherDuck account.
2. Generate an access token via the MotherDuck UI.
3. Store the token securely for configuration.

Usage with Claude Desktop

1. Install Claude Desktop if you haven't already.
2. Open the Claude Desktop configuration file. Add the following to claude_desktop_config.json:

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

• Replace <YOUR_MOTHERDUCK_TOKEN_HERE> with your actual token.

Example Queries

• "Create a new database and table in MotherDuck."
• "Query data from my local CSV file."
• "Join data from my local DuckDB with a table in MotherDuck."
• "Analyze data stored in Amazon S3."

Testing

1. Default MotherDuck database:

   uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>
   

2. Specific MotherDuck database:

   uvx mcp-server-motherduck --db-path md:your_database_name --motherduck-token <your_motherduck_token>
   

3. Local DuckDB database:

   uvx mcp-server-motherduck --db-path /path/to/your/local.db
   

4. In-memory database:

   uvx mcp-server-motherduck --db-path :memory:
   

Running in SSE mode

Run in SSE mode using supergateway:

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

Troubleshooting

• Verify your MotherDuck token for connection issues.
• Ensure the --home-dir parameter is set correctly for local file access.
• Check that the uvx command is available in your PATH.
• Specify the full path to uvx if you encounter spawn uvx ENOENT errors.

License

This MCP server is licensed under the MIT License, allowing free use, modification, and distribution per its terms. For more details, refer to the LICENSE file in the project repository.