用途
mcp-server-motherduck 是一个本地 MCP（Model Context Protocol）服务器，用于为 AI 助手和 IDE 提供 SQL 分析与数据工程能力。它把 DuckDB 的分析型 SQL 引擎与 MotherDuck 服务接入到兼容 MCP 的客户端中，使 AI 助手能够直接查询和分析数据。
主要能力
- 连接多种数据源：本地 DuckDB 文件、内存数据库、S3 上托管的 DuckDB 文件（s3://bucket/path.duckdb）以及 MotherDuck。
- 执行 SQL 读写查询。
- 浏览数据库目录。
- 在不同数据库连接之间即时切换（需 --allow-switch-databases 标志）。
- 所有工具返回 JSON；结果默认限制为 1024 行 / 50,000 字符，可通过 --max-rows、--max-chars 配置。
使用方式
前置条件：通过 pip install uv 或 brew install uv 安装 uv。
支持三种典型连接模式：
- 内存 DuckDB（开发模式）：完全灵活、无防护，具备读写访问权限，并可在运行时切换到任意数据库（本地文件、S3 或 MotherDuck）。
- 本地 DuckDB 文件（只读模式）：以只读方式连接特定 DuckDB 文件，不会持有文件锁，便于与同一文件的写入连接同时使用；也可通过 s3://bucket/path.duckdb 连接 S3 上的远程 DuckDB 文件（S3 认证见环境变量）。
- MotherDuck（读写模式）。
任何兼容 MCP 的客户端均可使用该服务器。将快速开始中的 JSON 配置添加到客户端的 MCP 配置文件中，配置文件位置请查阅对应客户端文档。例如 Kiro 的 MCP 配置文件位于 ~/.kiro/settings/mcp.json（全局）或 .kiro/settings/mcp.json（项目级）。
也可使用 Streamable HTTP 在 8000 端口构建并运行服务器（默认使用内存 DuckDB），MCP 端点位于 http://localhost:8000/mcp；通过传递 token 并覆盖命令可连接 MotherDuck。CLI 标志和环境变量同样适用。
从源码运行、命令行参数、环境变量等更多选项见项目文档。
适用场景
- 为 AI 助手和 IDE 提供 SQL 分析与数据工程支持。
- 连接本地 DuckDB 文件、内存数据库、S3 数据库或 MotherDuck 进行数据查询。
- 需要浏览数据库目录或在多个数据库连接间切换的分析工作流。
限制与安全注意事项
- 当向第三方开放自托管 MCP 服务器时，仅使用只读模式并不足够——它仍允许访问本地文件系统、更改 DuckDB 设置以及其他潜在敏感操作。
- 生产环境且涉及第三方访问时，官方推荐使用 MotherDuck Remote MCP（零配置、支持读写、由 MotherDuck 托管）。
- 自托管 MotherDuck MCP：可 fork 本仓库并按需定制；使用具有 read-scaling token 的服务账号，并启用 SaaS 模式以限制本地文件访问。
- 自托管 DuckDB MCP：使用 --init-sql 应用安全设置，参见 Securing DuckDB 指南。
- 故障排查：出现 spawn uvx ENOENT 时，指定 uvx 的完整路径（运行 which uvx 查找）；出现文件锁定（File locked）时，确保 --ephemeral-connections 已开启（默认 true），且未以读写模式连接。
其他信息
- 许可证：MIT（见 LICENSE 文件）。
- MCP 名称：io.github.motherduckdb/mcp-server-motherduck。
- 发布流程：运行 Release New Version GitHub Action，输入 MAJOR.MINOR.PATCH 格式的版本号，工作流会更新版本、发布到 PyPI/MCP registry，并创建包含 MCPB 包的 GitHub release。
