Che Duckdb MCP

使用 che-duckdb-mcp

DuckDB文档和数据库MCP服务器 --用于DuckDB文档搜索和数据库操作的Swift原生解决方案。

英语 | 繁体中文

______________________________________________________________________

为什么选择che-duckdb-mcp？

______________________________________________________________________

安装

三种安装方式，选择适合您工作流程的方式。

1.克劳德代码插件（推荐——自动下载）

/plugin marketplace add psychquant-claude-plugins
/plugin install che-duckdb-mcp@psychquant-claude-plugins

首次使用时，插件的包装器脚本会自动下载最新的 CheDuckDBMCP 二进制从 到 ~/bin/。无需手动构建。

2.手动二进制（适用于克劳德代码 claude mcp add)

# Option A: download pre-built binary
mkdir -p ~/bin
curl -L -o ~/bin/CheDuckDBMCP \
  https://github.com/PsychQuant/che-duckdb-mcp/releases/latest/download/CheDuckDBMCP
chmod +x ~/bin/CheDuckDBMCP

# Option B: build from source (requires Swift 5.9+, macOS 13+)
git clone https://github.com/PsychQuant/che-duckdb-mcp.git
cd che-duckdb-mcp
swift build -c release
cp .build/release/CheDuckDBMCP ~/bin/

# Register with Claude Code
claude mcp add --scope user --transport stdio che-duckdb-mcp -- ~/bin/CheDuckDBMCP

3.克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-duckdb-mcp": {
      "command": "/Users/YOUR_USERNAME/bin/CheDuckDBMCP"
    }
  }
}

安装后，重新启动Claude Code/Claude Desktop以加载新的MCP服务器。

______________________________________________________________________

全部14个工具

Documentation Tools (8)

Database Tools (6)

______________________________________________________________________

使用示例

文档查询

"Search for how to use read_csv"
"How do I use the json_extract function?"
"What's the syntax for COPY statement?"
"List all DuckDB functions"

数据库操作

"Connect to an in-memory database"
"Create a users table with id and name columns"
"Insert some test data"
"Show all users in Markdown format"
"List all tables"
"Describe the users table structure"

文件数据库连接

"Connect to /path/to/database.duckdb"
"Open the database in read-only mode"

______________________________________________________________________

输出格式

db_query 支持三种输出格式：

JSON格式（默认）

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

Markdown格式（推荐阅读）

| id | name  |
|---:|-------|
| 1  | Alice |
| 2  | Bob   |

CSV格式

id,name
1,Alice
2,Bob

______________________________________________________________________

安全考虑

1. 查询验证: db_query 仅允许SELECT、WITH、SHOW、DESCRIBE、EXPLAIN、PRAGMA
2. 资源限制：默认限制为每个查询1000行
3. 只读模式：支持以只读模式打开数据库
4. 仅限本地访问：仅支持本地文件，不支持远程连接

______________________________________________________________________

v2.0中的新增功能

• TF-IDF搜索引擎 --倒排索引+余弦相似度排名，比子字符串匹配好几个数量级
• 双源文件 --合并 llms.txt （3 KB LLM参考）和 duckdb-docs.md （5 MB完整文档）；llms.txt匹配获得1.5倍分数奖励
• 模糊函数匹配 --大小写/下划线规范化的Levenshtein距离≤2(read_csvs → read_csv, JSON_EXTRACT → json_extract)
• 条件HTTP缓存 --ETag/Last Modified取代了旧的24小时固定到期，因此5 MB文档blob不再每天重新下载
• Pinned duckdb快速修订版 --不再有来自自动上游更新的存储格式中断
• 存储版本兼容性检查 — db_connect 打开前读取文件头
• 真实DuckDB错误消息 — Binder Error / Catalog Error / Parser Error 现在，通过MCP响应，表面变得干净，而不是不透明 DuckDB.DatabaseError error N (修复#1)

______________________________________________________________________

技术细节

• 当前版本：v2.0.0
• 框架: MCP Swift SDK v0.12.0
• DuckDB绑定: duckdb swift 固定修订 d90cf8d （DuckDB v1.5.0-dev）
• 运输标准： stdio
• 平台：macOS 13.0+（文图拉及更高版本）
• 工具14个工具（8个文档+6个数据库）

______________________________________________________________________

缓存位置

• 缓存目录: ~/.cache/che-duckdb-mcp/

- llms.txt --轻量级LLM参考 - duckdb-docs.md --完整文档 - cache-meta.json --ETag/上次修改元数据

• 更新策略：HTTP条件请求（无固定过期）

______________________________________________________________________

故障排除

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

作者

由...创建 车成 (@kiki830621)

如果你觉得这个有用，请考虑给它一颗星！