DuckDB MCP Server

Name: DuckDB MCP Server
Author: mustafahasankhan

@mustafahasankhan

Repository

About DuckDB MCP Server

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

Basic information

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).