DuckDB MCP Server

DuckDB MCP 服务

一个 Model Context Protocol (MCP) 服务，可让 AI 助手全面访问 DuckDB——使用纯 SQL 查询本地文件、S3 存储桶和内存数据。

🌟 什么是 DuckDB MCP Server？

---

功能

此服务可向任何兼容 MCP 的客户端（Claude Desktop、Cursor、VS Code 等）开放 DuckDB。助手可以：

• 对本地 CSV、Parquet 和 JSON 文件运行任意 SQL
• 直接查询 S3 / GCS 存储桶，或将其缓存为本地表
• 检查架构、计算统计数据并推荐可视化图表
• 使用 DuckDB 的分析型 SQL 扩展（窗口函数、GROUP BY ALL、SELECT * EXCLUDE 等）

工具

工具	说明
query	执行任意 SQL 查询。结果最多返回 10 000 行。
analyze_schema	描述文件或表的列和类型。
analyze_data	行数、数值统计信息（最小值/最大值/平均值/中位数）、日期范围、最常见的分类值。
suggest_visualizations	根据列类型推荐图表类型和可直接运行的 SQL 查询。
create_session	创建或重置会话，以跟踪跨调用上下文。

资源

助手始终可以使用 3 个内置的 XML 文档资源：

资源 URI	内容
duckdb-ref://friendly-sql	DuckDB SQL 扩展（GROUP BY ALL、SELECT * EXCLUDE/REPLACE、FROM-first 语法等）
duckdb-ref://data-import	加载 CSV、Parquet、JSON 和 S3/GCS 数据；glob 模式；读取多个文件
duckdb-ref://visualization	时间序列图、柱状图、散点图和热力图的图表模式与查询模板

---

要求

• Python 3.10+
• 兼容 MCP 的客户端

安装

pip install duckdb-mcp-server

从源代码安装：

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

---

配置

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

标志	必需	说明
--db-path	是	DuckDB 文件的路径。如果文件不存在，则自动创建。
--readonly	否	以只读模式打开数据库。如果文件不存在，则报错。
--s3-region	否	AWS 区域。默认使用 AWS_DEFAULT_REGION 环境变量，其次使用 us-east-1。
--s3-profile	否	AWS 配置文件名称。默认使用 AWS_PROFILE 环境变量，其次使用 default。
--creds-from-env	否	从环境中读取 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY。

---

客户端设置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

使用 S3 访问权限

{
  "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"
      }
    }
  }
}

只读模式

适用于数据库由多人共享或单独管理的情况：

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

---

对话示例

查询本地文件

“加载 sales.csv，并显示收入最高的 5 种产品。”

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

使用 S3 数据

“缓存本月来自 S3 的注册数据，并按天汇总。”

-- 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;

统计分析

“为 orders 表提供统计摘要。”

助手会调用 analyze_data("orders")，返回行数、每列的数值统计信息、日期范围和最常见的分类值——无需你编写 SQL。

---

AWS 凭证解析顺序

1. 环境变量（--creds-from-env）：AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
2. 命名配置文件（--s3-profile）：读取 ~/.aws/credentials
3. 凭证链：环境变量 → 共享凭证文件 → 实例配置文件（EC2/ECS）

---

开发

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

---

许可证

欢迎贡献！请随时提交 Pull Request。 MIT