MotherDuck

DuckDB / MotherDuck 本地 MCP 服务器

面向 AI 助手和 IDE 的 SQL 分析与数据工程。

使用 DuckDB 强大的分析型 SQL 引擎，将 AI 助手连接到您的数据。支持连接本地 DuckDB 文件、内存数据库、S3 托管的数据库以及 MotherDuck。允许执行 SQL 读写查询、浏览数据库目录，并动态切换不同的数据库连接。

正在寻找 MotherDuck 的全托管远程 MCP 服务器？ → 前往 MotherDuck 远程 MCP 文档

远程与本地 MCP 对比

📝 从 v0.x 迁移？

• 默认只读：服务器现在默认以只读模式运行。添加 --read-write 以启用写访问。请参阅生产环境安全加固。
• 默认数据库已更改：--db-path 默认值从 md: 更改为 :memory:。显式添加 --db-path md: 以使用 MotherDuck。
• MotherDuck 只读模式需要读取扩展令牌：只读模式下的 MotherDuck 连接需要读取扩展令牌。常规令牌需要 --read-write。

快速开始

前提条件：通过 pip install uv 或 brew install uv 安装 uv

连接到内存 DuckDB（开发模式）

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

完全灵活，无防护栏 — 读写访问，并能在运行时切换到任何数据库（本地文件、S3 或 MotherDuck）。

以只读模式连接到本地 DuckDB 文件

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

以只读模式连接到特定的 DuckDB 文件。不会持有文件锁，因此可以方便地与同一 DuckDB 文件的写连接一起使用。您也可以使用 s3://bucket/path.duckdb 连接到 S3 上的远程 DuckDB 文件 — 有关 S3 身份验证，请参阅环境变量。如果您考虑让第三方访问 MCP，请参阅生产环境安全加固。

以读写模式连接到 MotherDuck

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

有关更多选项，请参阅命令行参数；有关部署指南，请参阅生产环境安全加固；如果遇到问题，请参阅故障排除。

客户端设置

客户端	配置位置	一键安装
Claude Desktop	设置 → 开发者 → 编辑配置	.mcpb (MCP Bundle)
Claude Code	使用下方的 CLI 命令	-
Codex CLI	使用下方的 CLI 命令或 ~/.codex/config.toml	-
Gemini CLI	使用下方的 CLI 命令或 ~/.gemini/settings.json	-
Cursor	设置 → MCP → 添加新的全局 MCP 服务器
VS Code	Ctrl+Shift+P → “首选项：打开用户设置 (JSON)”
Kiro	~/.kiro/settings/mcp.json（全局）或 .kiro/settings/mcp.json（项目）

任何兼容 MCP 的客户端都可以使用此服务器。将快速开始中的 JSON 配置添加到客户端的 MCP 配置文件中。有关配置文件的位置，请查阅客户端的文档。

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

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

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

工具

*需要 --allow-switch-databases 标志

所有工具都返回 JSON。默认情况下，结果限制为 1024 行 / 50,000 个字符（可通过 --max-rows、--max-chars 配置）。

生产环境安全加固

当让第三方访问自托管的 MCP 服务器时，仅靠只读模式是不够的 — 它仍然允许访问本地文件系统、更改 DuckDB 设置以及其他潜在的敏感操作。

对于涉及第三方访问的生产部署，我们推荐 MotherDuck 远程 MCP — 零设置、支持读写，并由 MotherDuck 托管。

自托管 MotherDuck MCP： Fork 本仓库并根据需要进行自定义。使用 服务账号 和 读取扩展令牌，并启用 SaaS 模式 以限制本地文件访问。

自托管 DuckDB MCP： 使用 --init-sql 应用安全设置。有关可用选项，请参阅保护 DuckDB 指南。

Docker

构建并使用 Streamable HTTP 在端口 8000 上运行服务器（默认为内存 DuckDB）：

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

通过传递令牌并覆盖命令来连接到 MotherDuck：

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

MCP 端点位于 http://localhost:8000/mcp。下方的 CLI 标志和环境变量仍然适用。

命令行参数

环境变量

故障排除

• spawn uvx ENOENT：指定 uvx 的完整路径（运行 which uvx 来查找它）
• 文件被锁定：确保 --ephemeral-connections 已开启（默认：true），并且您没有以读写模式连接

资源

• MotherDuck MCP 文档
• 闭环：使用 MCP、DuckDB 和 AI 实现更快的数据管道（博客）
• 使用 MCP 和 DuckDB 实现更快的数据管道（YouTube）

开发

从源代码运行：

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

发布流程

1. 运行 Release New Version GitHub Action
2. 以 MAJOR.MINOR.PATCH 格式输入版本号
3. 工作流将更新版本号、发布到 PyPI/MCP 注册表，并创建包含 MCPB 包的 GitHub 发布版本

许可证

MIT 许可证 - 请参阅 LICENSE 文件。

mcp-name: io.github.motherduckdb/mcp-server-motherduck