motherduckdb/mcp-server-motherduck

DuckDB / MotherDuck 本地 MCP 服务器 – 快速概览

是什么 – 一个极小的自托管服务器，支持 AI 助手工具（Claude、Gemini、Cursor 等）使用的 MCP（Model-Chat-Protocol）协议。它封装了 DuckDB（一个快速、可嵌入的分析型 SQL 引擎），使这些助手能够对以下目标执行 SQL 查询：

• 本地 DuckDB 文件，
• 内存中的 DuckDB 实例（非常适合开发），
• 存储在 S3 上的 DuckDB 文件，或
• MotherDuck 云数据库（md:）。

对 AI 的意义 – 现代 AI 助手需要最新数据才能回答问题或编写代码。通过 MCP 暴露 DuckDB，助手可以发出标准 SQL（SELECT …）并以 JSON 格式接收结果，完全无需离开聊天界面。

---

核心功能（如 README 所述）

功能	详情
SQL 引擎	使用 DuckDB 的分析型 SQL 语法；支持读写查询。
多种后端	本地文件、内存、S3 托管 DuckDB 或 MotherDuck（md:）。
MCP 兼容	与任何实现 MCP 规范的客户端兼容（Claude Desktop/Code、Gemini、Cursor、Codex、Kiro 等）。
传输选项	stdio（默认，用于基于 CLI 的客户端）或 HTTP（--transport http）。
动态数据库切换	启用 --allow-switch-databases 后，工具可在运行时切换底层数据库。
安全控制	只读模式、可选的基于令牌的 MotherDuck 认证、SaaS 模式标志，以及通过 --init-sql 实现的 DuckDB 级别加固。
Docker 就绪	提供官方 Dockerfile；运行在端口 8000，支持通过环境变量配置凭证。
工具支持	内置 JSON 返回工具：execute_query、list_databases、list_tables、list_columns、switch_database_connection。
限制	默认限制：每响应最多 1,024 行 / 50,000 字符（可配置）。

---

典型使用流程

1. 安装 uv（Python 包管理器）– pip install uv。
2. 启动服务器 使用单条命令，例如：

   uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases
   

   此命令启动一个可被助手读写内存中的 DuckDB。
3. 配置 AI 客户端 – 将 README 中所示的 JSON 片段添加到客户端的 MCP 配置中。客户端通过 stdio 或 HTTP 与服务器通信。
4. 执行查询 – 助手调用 execute_query 工具，接收 JSON 行，并可迭代、连接或可视化数据。
5. 生产环境 – 对外部用户，README 建议使用 MotherDuck 的托管 Remote MCP，或通过只读模式、服务账户令牌和 DuckDB 加固来保护自托管服务器。

---

如何开始（分步指南）

1. 前提条件 – 安装 uv。
2. 选择后端 – 内存（:memory:）、本地文件（/path/to.db）、S3（s3://bucket/file.duckdb）或 MotherDuck（md:）。
3. 运行 – 本地文件只读示例：

   uvx mcp-server-motherduck --db-path /abs/path/to.db
   

4. 添加到客户端 – 对于 Claude Desktop，下载提供的 .mcpb 包；对于 Cursor，点击安装按钮；对于 VS Code，使用 UV 安装徽章。
5. 查询 – 使用 execute_query 工具，例如：{ "sql": "SELECT * FROM orders LIMIT 10" }。

---

安全与生产建议（来自 README）

• 只读模式 不会阻止文件系统访问；对外部暴露时建议使用 Remote MCP。
• 使用 MotherDuck 服务账户令牌 并启用 读取扩展，同时启用 SaaS 模式 以限制本地文件访问。
• 对自托管 DuckDB，使用 --init-sql 提供 DuckDB 安全设置（参见 DuckDB 文档）。
• 在 Docker 中运行，并仅暴露所需端口。

---

许可证

MIT – 可自由使用、修改和重新分发。

---

总结 – 该项目提供了一个轻量级桥梁，使现代 AI 助手可通过标准 MCP 协议将 DuckDB（或 MotherDuck）作为实时数据源，实现在 IDE 和聊天工具中的实时 SQL 驱动交互。