MotherDuck

DuckDB / MotherDuck 本地 MCP 服务器

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

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

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

远程 MCP 与本地 MCP 对比

快速开始

前置条件：通过 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 捆绑包）
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： 分叉此仓库并根据需要进行自定义。使用带有 读取扩展令牌 的 服务账户，并启用 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