MotherDuck's DuckDB MCP Server

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	Settings → Developer → Edit Config	.mcpb (MCP Bundle)
Claude Code	使用下方的 CLI 命令	-
Codex CLI	使用下方的 CLI 命令或 ~/.codex/config.toml	-
Gemini CLI	使用下方的 CLI 命令或 ~/.gemini/settings.json	-
Cursor	Settings → MCP → Add new global MCP server
VS Code	Ctrl+Shift+P → "Preferences: Open User Settings (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

在端口 8000 上使用 Streamable HTTP 构建并运行服务（默认使用内存中的 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