AI导哈

DuckDB SQL服务器

一个为AI助手提供完整DuckDB访问权限的MCP服务器，允许通过SQL查询本地文件、S3存储桶和内存数据。

  • by mustafahasankhan
  • Python
  • 本地部署
  • 19 星标
  • 更新于
在 GitHub 查看 mustafahasankhan/duckdb-mcp-server

使用说明

DuckDB MCP服务器

A. 模型上下文协议（MCP） 允许AI助手完全访问的服务器 鸭数据库 --使用纯SQL查询本地文件、S3存储桶和内存中的数据。

🌟 什么是DuckDB MCP服务器？

它做什么

此服务器将DuckDB暴露给任何兼容MCP的客户端（Claude Desktop、Cursor、VS Code等）。助理可以：

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

工具

工具 说明
query 执行任何SQL查询。结果限制在10000行以内。
analyze_schema 描述文件或表的列和类型。
analyze_data 行数、数字统计（最小/最大/平均/中值）、日期范围、顶级分类值。
suggest_visualizations 建议图表类型，并根据列类型准备运行SQL查询。
create_session 创建或重置会话以进行跨呼叫上下文跟踪。

资源

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

资源URI 内容
duckdb-ref://friendly-sql DuckDB SQL扩展（按所有分组、选择*排除/替换、从第一语法开始…）
duckdb-ref://data-import 加载CSV、Parquet、JSON和S3/GCS数据；球状图案；多文件读取
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 那么，env-var us-east-1.
--s3-profile 否 AWS配置文件名称。默认为 AWS_PROFILE 那么，env-var default.
--creds-from-env 否 阅读 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 从环境。

客户端设置

克劳德桌面版

编辑 ~/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.cv，向我显示按收入排名前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;

统计分析

“给我一份订单表的统计摘要。”

助理打来电话 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

许可证

欢迎投稿！请随时提交拉取请求。 麻省理工学院

相关 MCP