How to Set Up DuckDB MCP Server for AI-Powered SQL Analytics

Supercharge your data analytics workflow by connecting AI assistants and IDEs directly to DuckDB and MotherDuck databases—no manual SQL required. Discover how the DuckDB MCP Server lets you run natural language queries, automate data exploration, and boost productivity with tools like Cursor, Claude Desktop, and VS Code.

💡 Looking for a robust API testing platform that also generates beautiful API documentation? Need an all-in-one workspace for your developer team’s productivity? Try Apidog—it replaces Postman at a much more affordable price while streamlining your API workflow.

What is DuckDB MCP Server? The Bridge Between AI and SQL

The DuckDB MCP Server is a Model Context Protocol (MCP) server that enables direct, conversational SQL queries from AI tools to DuckDB and MotherDuck databases. This means you can ask your AI client questions like “Show me the top customers,” and instantly get results—no manual SQL or context switching.

Key Features:

• Hybrid Execution: Query both local DuckDB files and MotherDuck’s cloud-based databases.
• Cloud Storage Access: Seamlessly analyze data from AWS S3 or other providers via MotherDuck.
• Natural Language SQL: Leverage AI to run SQL from plain English prompts.
• Serverless Simplicity: No clusters or heavy infrastructure management.

DuckDB MCP Server is rapidly becoming a favorite among data analysts and developers for AI-driven analytics.

Why Use DuckDB MCP Server for Data Analytics?

If you’re an API developer, data engineer, or technical lead, DuckDB MCP Server unlocks several advantages:

• Conversational Analytics: Query databases using everyday language.
• Flexible Data Sources: Connect to on-premises, in-memory, or cloud data.
• Secure Integrations: Use token-based authentication for MotherDuck.
• AI Tool Compatibility: Instantly query via Cursor, Claude Desktop, or VS Code.

For example, generating sales trend reports becomes as simple as typing a question—no more manual queries or tedious data wrangling.

Step-by-Step: Setting Up DuckDB MCP Server

Follow this guide to install and configure DuckDB MCP Server for both cloud (MotherDuck) and local (DuckDB) use cases.

1. Install Prerequisites

Ensure you have:

• Python 3.8+ and pip. Check versions:

  python --version
  pip --version
  

• uv CLI tool:

  pip install uv
  

  Or for Mac:

  brew install uv
  

  Confirm installation:

  uv --version
  

• MotherDuck Account (for cloud):
  Sign up at app.motherduck.com, then generate an access token from Settings > Tokens.

2. Choose Your Data Source

Option 1: MotherDuck Cloud (S3 & Cloud Storage)

• Best for cloud-hosted datasets.
• Install the MCP server:

  pip install mcp-server-motherduck
  

Option 2: Local DuckDB (On Your Device)

• Ideal for working with local CSV or DuckDB database files.
• Download the DuckDB CLI from duckdb.org/docs/installation/.

• Run the CLI and try with a sample dataset (e.g., netflix_daily_top_10.csv from github.com/mehd-io/duckdb-tutorial-for-beginner).

  Example DuckDB commands:

  FROM read_csv_auto('./path/to/csv/netflix_daily_top_10.csv') LIMIT 3;
  CREATE TABLE netflix_data AS FROM read_csv_auto('./path/to/csv/netflix_daily_top_10.csv');
  SHOW tables;
  

3. Start the DuckDB MCP Server

For 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>

For Local DuckDB Files:

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

For In-Memory DB:

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

4. Connect DuckDB MCP Server to Your AI Tool

Cursor (Cloud & Local)

• Download from cursor.com/downloads.
• Go to Settings > Tools & Integrations > + Add new Custom MCP Server.
• Edit ~/.cursor/mcp.json as follows:

Cloud Example:

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

Local Example:

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

Claude Desktop

• Get Claude Desktop from claude.ai/download.
• Edit the config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

Cloud Example:

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

Local Example:

{
  "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> as needed and restart Claude.

VS Code

• Open Preferences: Open User Settings (JSON) (Ctrl+Shift+P).
• Add the server configuration:

Cloud Example:

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

Local Example:

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

Save and reload VS Code.

5. Query Your Database Using AI

Now, simply prompt your AI tool:

• Cloud: “Show top 10 customers by revenue.”
• Local: “List top 3 Netflix shows by days in top 10.”
• SQL Command: “Run: SELECT * FROM orders WHERE status = 'shipped';”

Results appear instantly inside your AI client.

6. Example: Data Exploration with DuckDB MCP Server

For a database containing matches and players tables, try these prompts:

• “Which tables are available?”
• “Which country has the most players?”
• “Which player has won the most finals?”

7. Best Practices: Securing Your DuckDB MCP Server

For collaborative environments or production:

• Read Scaling Token: Use a MotherDuck read-only token for up to 4 replicas.
• SaaS Mode: Restrict local file access for security:

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

Troubleshooting Common DuckDB MCP Server Issues

• spawn uvx ENOENT: Confirm uvx is in your PATH with which uvx.
• Token errors: Double-check your token at app.motherduck.com/settings/tokens.
• Server not responding: Ensure port 5000 is free or restart the process.
• Query issues: Use DESCRIBE table_name; to inspect schemas.
• DuckDB CLI issues: Make sure the .exe and CSV paths are correct.

For more help, see motherduck.com/docs or github.com/motherduckdb/mcp-server-motherduck.

Customizing and Extending DuckDB MCP Server

Take your setup further:

• Custom Prompts: Try “Summarize Netflix shows by year.”
• Combine with dbt: Model data pipelines, then query via MCP Server.
• Access S3 Data: Query Parquet files directly using MotherDuck.
• Debugging: Use MCP Inspector for troubleshooting:

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

Why DuckDB MCP Server Changes How Developers Work

DuckDB MCP Server transforms the way technical teams interact with data—bridging natural language, AI, and SQL for rapid, accessible analytics. Its hybrid support for local and cloud data, serverless approach, and AI integrations set it apart from the traditional DuckDB CLI. While token management and permissions require attention, the time savings and productivity boost are immense.

💡 Want to improve your API workflow even further? Apidog provides seamless API documentation and team collaboration, helping you ship faster than ever—see how it compares to Postman.