How to Use DuckDB MCP Server

MotherDuck’s DuckDB MCP Server is a powerful tool that enables AI assistants and IDEs to interact directly with DuckDB and MotherDuck databases using SQL queries. This server implements the Model Context Protocol (MCP), allowing seamless conversational SQL analytics and data exploration from your AI client like Claude Desktop, Cursor, or VS Code. I got it running in ~20 minutes, and it’s a total game-changer for data analytics!

In this guide, you’ll learn how to install, configure, and use the MotherDuck MCP server both locally and with cloud databases, plus how to integrate it with popular AI clients.

💡

Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demands, and replaces Postman at a much more affordable price!

button

What is DuckDB MCP Server? Your AI-SQL Sidekick

The DuckDB MCP Server is a Model Context Protocol (MCP) server that connects AI clients to DuckDB and MotherDuck databases for seamless SQL analytics. It lets you run queries conversationally, like asking, “Show me top customers!” Here’s why DuckDB MCP Server rocks:

Hybrid Execution: Query local DuckDB files or cloud-based MotherDuck databases.
Cloud Storage: Access data on AWS S3 or other cloud providers via MotherDuck.
AI-Powered SQL: Run SQL queries through natural language in AI tools.
Serverless: No need to manage database clusters—pure simplicity.

X users call DuckDB MCP Server a “killer tool” for AI-driven data exploration. Ready to try it? Let’s set it up!

Why Use DuckDB MCP Server?

DuckDB MCP Server is a must for data analysts, devs, or anyone wanting AI to handle SQL tasks. Benefits include:

Conversational Analytics: Ask questions in plain English, get SQL results.
Flexible Data Sources: Works with local files, in-memory databases, or cloud.
Secure Integration: Uses tokens for safe MotherDuck access.
AI Tool Support: Plugs into Cursor, Claude, or VS Code for instant queries.

I used it to pull sales trends in seconds—way faster than manual SQL!

How to Set Up DuckDB MCP Server: Step-by-Step Guide

Let’s get the DuckDB MCP Server running for cloud (MotherDuck) or local (DuckDB) data. You’ll need Python 3.8+, pip, and an AI client (Cursor, Claude Desktop, or VS Code). Choose your data source and follow along!

1. Install Prerequisites

Python 3.8+ and pip: Verify installation:

python --version
pip --version

uv CLI Tool: Install via pip or Homebrew:

pip install uv

Or on macOS:

brew install uv

Check PATH:

uv --version

MotherDuck Account (Cloud Option): Sign up at app.motherduck.com and grab your token from Settings > Tokens.

2. Choose Your Data Source

Option 1: MotherDuck Cloud (AWS S3/Cloud Storage)

Ideal for cloud-hosted data (e.g., S3). Sign up at motherduck.com and get your token.
Install the server package:

pip install mcp-server-motherduck

Option 2: Local DuckDB (On Your Machine)

Perfect for local CSV or database files. Install DuckDB CLI:
Download the CLI for your OS (e.g., Windows x86_64) from duckdb.org/docs/installation/.

Run the .exe to open the DuckDB CLI.
Download the sample dataset netflix_daily_top_10.csv from github.com/mehd-io/duckdb-tutorial-for-beginner.

In the DuckDB CLI:

View CSV: FROM read_csv_auto('./path/to/csv/netflix_daily_top_10.csv') LIMIT 3;

Create table: CREATE TABLE netflix_data AS FROM read_csv_auto('./path/to/csv/netflix_daily_top_10.csv');
View table: FROM netflix_data;
List tables: SHOW tables;

Play with DuckDB to get comfy!

3. Run the DuckDB MCP Server

Start the server based on your data source.

MotherDuck Cloud:

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

Or for a specific database:

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

Local DuckDB:

Local file:

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

In-memory:

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

4. Configure DuckDB MCP Server in AI Clients

Connect your AI tool to the DuckDB MCP Server.

Cursor (Cloud Option):

Install Cursor from cursor.com/downloads.
Go to Settings > Tools & Integrations > + Add new Custom MCP Server.

Edit ~/.cursor/mcp.json:

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

Cursor (Local Option):

For in-memory:

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

For local file (e.g., netflix_data.db):

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

Save and restart Cursor.

Claude Desktop (Cloud Option):

Install Claude Desktop from claude.ai/download.
Open Settings > Developer > Edit Config to access ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows).
Add:

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

Claude Desktop (Local Option):

For local file:

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

Replace <YOUR_HOME_DIRECTORY> (e.g., /Users/yourname). Restart Claude.

VS Code (Cloud Option):

Open Ctrl+Shift+P, type Preferences: Open User Settings (JSON).
Add:

{
  "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}"
        ]
      }
    }
  }
}

VS Code (Local Option):

For local file:

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

Save and reload VS Code.

5. Use DuckDB MCP Server

Query your database via AI prompts:

Cloud: “Show top 10 customers by revenue.”
Local (Netflix data): “What are the top 3 Netflix shows by days in top 10?”
General: “Run: SELECT * FROM orders WHERE status = 'shipped';”

Results appear in your AI client. I queried Netflix data, and it was lightning-fast!

6. Test DuckDB MCP Server

For a database with matches and players tables:

List tables: “What tables are available in the database?”

Insights: “Which country has the most players?”

Deep dive: “Which player has reached and won the most finals?”

I tested “most finals” and got a clear winner—super insightful!

7. Secure Your DuckDB MCP Server

For shared setups:

Read Scaling Token: Use a MotherDuck read-only token (from UI) for up to 4 replicas.
SaaS Mode: Restrict local file access:

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

Troubleshooting DuckDB MCP Server Issues

“spawn uvx ENOENT”: Run which uvx to check PATH.
Token Auth Fails: Verify token at app.motherduck.com/settings/tokens.
Server Not Responding: Check port 5000 or restart.
Query Errors: Use DESCRIBE table_name; to inspect schema.
DuckDB CLI Issues: Ensure .exe ran correctly and CSV path is valid.
Need Help? Visit motherduck.com/docs or github.com/motherduckdb/mcp-server-motherduck.

Customizing and Extending DuckDB MCP Server

Level up:

Custom Prompts: Try “Summarize Netflix shows by year.”
Workflows: Pair with dbt for modeling, query via DuckDB MCP Server.
S3 Queries: Access Parquet files on S3 with MotherDuck.
Debugging: Use MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory ~/mcp-server-motherduck run mcp-server-motherduck --db-path :memory:

I queried S3 data with one prompt—mind blown!

Why DuckDB MCP Server is a Data Game-Changer

DuckDB MCP Server turns your AI into a SQL powerhouse, blending local and cloud data with conversational ease. Its serverless design and MotherDuck integration outshine traditional tools for quick analytics. Tokens can be tricky, but the MotherDuck docs help. Compared to DuckDB CLI, DuckDB MCP Server adds AI smarts and MCP flexibility.

Ready to query like a pro? Spin up DuckDB MCP Server, try those prompts, and share your setup—I’m stoked to see your data wins!

💡

button