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

Redis

modelcontextprotocol

Model Context Protocol Servers

88.2K

ClickHouse MCP Server

ClickHouse

Connect ClickHouse to your AI assistants.

818

Multi Database MCP Server

FreePeak

A powerful multi-database server implementing the Model Context Protocol (MCP) to provide AI assistants with structured access to databases.

397

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

Neon MCP Server

neondatabase-labs

MCP server for interacting with Neon Management API and databases

617