AI导哈

DuckDB文档搜索与数据库服务

一个集成了DuckDB文档搜索和数据库操作的Swift原生解决方案，支持TF-IDF文档搜索、模糊函数匹配、多格式输出等功能。

  • by PsychQuant
  • Swift
  • 本地部署
  • 更新于
在 GitHub 查看 kiki830621/che-duckdb-mcp

使用说明

使用 che-duckdb-mcp

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

英语 | 繁体中文

为什么选择che-duckdb-mcp？

功能 其他DuckDB mcp che-DuckDB mcp v2
数据库查询 是 是
TF-IDF文档搜索 没有 是 （倒索引+余弦相似度）
模糊函数匹配 没有 是 （Levenshtein≤2）
双源文档 （llms.txt+完整） 否 是
SQL语法参考 没有 是
多种输出格式 一些 是 （JSON/Markdown/CSV）
内存数据库 一些 是
Rich DuckDB错误消息 部分 是 （活页夹/目录/解析器）
语言 Python Swift（原生二进制，零运行时deps）

安装

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

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

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

首次使用时，插件的包装器脚本会自动下载最新的 CheDuckDBMCP 二进制从 GitHub发布 到 ~/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)
工具 描述 只读
search_docs 按关键字搜索DuckDB文档 ✓
list_sections 列出所有文档部分 ✓
get_section 获取特定部分的内容 ✓
get_function_docs 获取DuckDB函数的文档 ✓
list_functions 列出所有记录的功能 ✓
get_sql_syntax 获取SQL语法文档 ✓
refresh_docs 强制重新下载文档 ✗
get_doc_info 获取文档缓存信息 ✓
Database Tools (6)
工具 描述 只读
db_connect 连接到数据库（文件或内存中） ✗
db_query 执行SELECT查询 ✓
db_execute 执行DDL/DML语句 ✗
db_list_tables 列出所有表和视图 ✓
db_describe 描述表结构或查询结果 ✓
db_info 获取当前连接信息 ✓

使用示例

文档查询

"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.3.0
  • 框架: MCP Swift SDK v0.12.0
  • DuckDB绑定: duckdb swift 固定修订 4d9fb7c （DuckDB v1.6.0-dev3343——读取R DuckDB v1.5.2编写的数据库）
  • 运输标准： stdio
  • 平台：macOS 13.0+（文图拉及更高版本）
  • 工具14个工具（8个文档+6个数据库）

缓存位置

  • 缓存目录: ~/.cache/che-duckdb-mcp/
    • llms.txt --轻量级LLM参考
    • duckdb-docs.md --完整文档
    • cache-meta.json --ETag/上次修改元数据
  • 更新策略：HTTP条件请求（无固定过期）

故障排除

问题 解决方案
服务器已断开连接 使用重建 swift build -c release
文档加载失败 请检查网络连接，或使用 refresh_docs
数据库连接失败 验证文件路径和读取权限

许可证

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

作者

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

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

相关 MCP