DuckDB MCP Server

@mustafahasankhan

About DuckDB MCP Server

A MCP server for DuckDB with auth and friendly sql support out of the box.

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "duckdb-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "venv",
        ".venv",
        "&&",
        "source",
        ".venv/bin/activate"
      ]
    }
  }
}

Tools

Execute any SQL query. Results capped at 10 000 rows.

Describe the columns and types of a file or table.

Row count, numeric stats (min/max/avg/median), date ranges, top categorical values.

Suggest chart types and ready-to-run SQL queries based on column types.

Create or reset a session for cross-call context tracking.

Overview

What is DuckDB MCP Server?

A Model Context Protocol (MCP) server that gives AI assistants full access to DuckDB — enabling them to query local files, S3/GCS buckets, and in-memory data using plain SQL. It is designed for any MCP-compatible client such as Claude Desktop, Cursor, or VS Code.

How to use DuckDB MCP Server?

Install with pip install duckdb-mcp-server, then configure via the --db-path flag (and optional --readonly, --s3-region, --s3-profile, --creds-from-env). After installation, set up the server in your client's MCP configuration file (e.g., claude_desktop_config.json). The server exposes five tools: query, analyze_schema, analyze_data, suggest_visualizations, and create_session.

Key features of DuckDB MCP Server

Execute arbitrary SQL queries (capped at 10,000 rows).
Analyze schema and data statistics for files or tables.
Suggest visualizations with ready-to-run SQL templates.
Query local CSV, Parquet, and JSON files directly.
Cache remote S3/GCS data as local tables.
Supports DuckDB SQL extensions (GROUP BY ALL, SELECT * EXCLUDE, etc.).
Read‑only mode for shared or externally managed databases.

Use cases of DuckDB MCP Server

Ask an AI assistant to load a local CSV and compute top products by revenue.
Cache monthly signups from S3 and produce daily breakdowns without writing SQL.
Get a statistical summary (row count, min/max/avg, date ranges) of any table.
Have the assistant suggest chart types and corresponding SQL queries based on column types.

FAQ from DuckDB MCP Server

What is DuckDB MCP Server?

It is an MCP server that connects AI assistants to DuckDB, allowing them to query local and remote data using SQL through tools like query, analyze_data, and suggest_visualizations.

How does DuckDB MCP Server handle AWS credentials?

Credentials are resolved in this order: 1) environment variables (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY when --creds-from-env is set), 2) a named AWS profile (--s3-profile), 3) the default credential chain (environment, shared credentials file, instance profile).

Can I use DuckDB MCP Server in read‑only mode?

Yes. Pass --readonly when starting the server; the database must already exist or an error is raised.

What is the row limit for query results?

The query tool caps results at 10,000 rows.

What Python version is required?

Python 3.10 or higher is required.

Frequently asked questions

What is DuckDB MCP Server?

It is an MCP server that connects AI assistants to DuckDB, allowing them to query local and remote data using SQL through tools like `query`, `analyze_data`, and `suggest_visualizations`.

How does DuckDB MCP Server handle AWS credentials?

Credentials are resolved in this order: 1) environment variables (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` when `--creds-from-env` is set), 2) a named AWS profile (`--s3-profile`), 3) the default credential chain (environment, shared credentials file, instance profile).

Can I use DuckDB MCP Server in read‑only mode?

Yes. Pass `--readonly` when starting the server; the database must already exist or an error is raised.

What is the row limit for query results?

The `query` tool caps results at 10,000 rows.

What Python version is required?

Python 3.10 or higher is required.

Comments

Basic information

More Databases MCP servers

nuzur

nuzur is a model-first database platform for MySQL and PostgreSQL. The MCP server lets any AI assistant or agent (Claude, Cursor, Gemini, or anything else that speaks MCP) design your schema, query your data, generate mi

MCP MongoDB Server

kiliczsh

A Model Context Protocol Server for MongoDB

281

MCP Server for MySQL based on NodeJS

benborla

A Model Context Protocol server that provides read-only access to MySQL databases. This server enables LLMs to inspect database schemas and execute read-only queries.

1.9K

mcp-server-qdrant: A Qdrant MCP server

qdrant

An official Qdrant Model Context Protocol (MCP) server implementation

637

MotherDuck's DuckDB MCP Server

motherduckdb

Local MCP server for DuckDB and MotherDuck

498