DuckDB MCP服务器
](https://pypi.org/project/duckdb-mcp-server/) ](https://pypi.org/project/duckdb-mcp-server/) 
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
[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凭证解析顺序
- 环境变量(
--creds-from-env):AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY - 命名配置文件(
--s3-profile)：阅读~/.aws/credentials - 凭证链：环境→ 共享凭据文件→ 实例配置文件（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______________________________________________________________________
许可证
欢迎投稿！请随时提交拉取请求。 麻省理工学院