DuckDB MCP Server

A Model Context Protocol (MCP) server that gives AI assistants full access to DuckDB — query local files, S3 buckets, and in-memory data using plain SQL.

🌟 What is DuckDB MCP Server?

---

What it does

This server exposes DuckDB to any MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.). The assistant can:

• Run arbitrary SQL against local CSV, Parquet, and JSON files
• Query S3 / GCS buckets directly or cache them as local tables
• Inspect schemas, compute statistics, and suggest visualizations
• Use DuckDB's analytical SQL extensions (window functions, GROUP BY ALL, SELECT * EXCLUDE, etc.)

Tools

Resources

Three built-in XML documentation resources are always available to the assistant:

---

Requirements

• Python 3.10+
• An MCP-compatible client

Installation

pip install duckdb-mcp-server

From source:

git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server
pip install -e .

---

Configuration

duckdb-mcp-server --db-path  [options]

---

Client setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": ["--db-path", "~/claude-duckdb/data.db"]
    }
  }
}

With S3 access

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": [
        "--db-path", "~/claude-duckdb/data.db",
        "--s3-region", "us-east-1",
        "--creds-from-env"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_KEY",
        "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET"
      }
    }
  }
}

Read-only mode

Useful when the database is shared or managed separately:

{
  "mcpServers": {
    "duckdb": {
      "command": "duckdb-mcp-server",
      "args": ["--db-path", "/shared/analytics.db", "--readonly"]
    }
  }
}

---

Example conversations

Querying a local file

"Load sales.csv and show me the top 5 products by revenue."

SELECT
    product_name,
    SUM(quantity * price) AS revenue
FROM read_csv('sales.csv')
GROUP BY ALL
ORDER BY revenue DESC
LIMIT 5;

Working with S3 data

"Cache this month's signups from S3 and show me a daily breakdown."

-- Step 1: cache the remote data locally
CREATE TABLE signups AS
  SELECT * FROM read_parquet('s3://my-bucket/signups/2026-03/*.parquet',
                             union_by_name = true);

-- Step 2: query the cached table
SELECT
    date_trunc('day', signup_at) AS day,
    COUNT(*)                     AS signups
FROM signups
GROUP BY ALL
ORDER BY day DESC;

Statistical analysis

"Give me a statistical summary of the orders table."

The assistant calls analyze_data("orders") which returns row count, numeric stats per column, date ranges, and top categorical values — no SQL required from you.

---

AWS credential resolution order

1. Environment variables (--creds-from-env): AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY

2. Named profile (--s3-profile): reads ~/.aws/credentials

3. Credential chain: environment → shared credentials file → instance profile (EC2/ECS)

---

Development

git clone https://github.com/mustafahasankhan/duckdb-mcp-server.git
cd duckdb-mcp-server

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest

---

License

Contributions are welcome! Please feel free to submit a Pull Request.

MIT