DuckDB MCP Server

PyPI - Version PyPI - Python Version PyPI - License

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

Tool	Description
`query`	Execute any SQL query. Results capped at 10 000 rows.
`analyze_schema`	Describe the columns and types of a file or table.
`analyze_data`	Row count, numeric stats (min/max/avg/median), date ranges, top categorical values.
`suggest_visualizations`	Suggest chart types and ready-to-run SQL queries based on column types.
`create_session`	Create or reset a session for cross-call context tracking.

Resources

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

Resource URI	Content
`duckdb-ref://friendly-sql`	DuckDB SQL extensions (GROUP BY ALL, SELECT * EXCLUDE/REPLACE, FROM-first syntax, …)
`duckdb-ref://data-import`	Loading CSV, Parquet, JSON, and S3/GCS data; glob patterns; multi-file reads
`duckdb-ref://visualization`	Chart patterns and query templates for time series, bar, scatter, and heatmap

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 <path> [options]

Flag	Required	Description
`--db-path`	Yes	Path to the DuckDB file. Created automatically if it does not exist.
`--readonly`	No	Open the database read-only. Errors if the file does not exist.
`--s3-region`	No	AWS region. Defaults to `AWS_DEFAULT_REGION` env var, then `us-east-1`.
`--s3-profile`	No	AWS profile name. Defaults to `AWS_PROFILE` env var, then `default`.
`--creds-from-env`	No	Read `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` from environment.

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

Environment variables (--creds-from-env): AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
Named profile (--s3-profile): reads ~/.aws/credentials
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