MotherDuck

官方

使用 MotherDuck 和本地 DuckDB 查询和分析数据

GitHub

504

你可以用 MotherDuck MCP 做什么？

对DuckDB或MotherDuck执行SQL查询 — 让您的助手通过execute_query运行分析型SQL，支持读取及可选写入操作。
探索数据库模式 — 使用list_databases列出可用数据库，然后通过list_tables和list_columns深入查看表和列。
切换数据库连接 — 使用switch_database_connection在运行时切换本地DuckDB文件、内存实例、S3托管的数据库或MotherDuck。
连接MotherDuck进行云分析 — 将服务器指向带有令牌的md:，直接查询和管理MotherDuck数据库。
控制查询输出大小 — 配置--max-rows和--max-chars以限制返回给助手的结果集大小。

文档

MotherDuck / DuckDB Local MCP Server

DuckDB / MotherDuck 本地 MCP 服务器

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

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

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

远程与本地 MCP 对比

	远程 MCP	本地 MCP（本仓库）
托管方式	由 MotherDuck 托管	本地运行/自行托管
设置	零设置	需要本地安装
访问	支持读写	支持读写
本地文件系统	-	跨本地和远程数据库查询，从本地文件系统摄取数据/导出数据到本地文件系统

📝 从 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 Code CLI 命令

内存 DuckDB（开发模式）：

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

本地 DuckDB（只读）：

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

MotherDuck（读写）：

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

Codex CLI 命令

内存 DuckDB（开发模式）：

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

本地 DuckDB（只读）：

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

MotherDuck（读写）：

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

Gemini CLI 命令

内存 DuckDB（开发模式）：

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

本地 DuckDB（只读）：

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

MotherDuck（读写）：

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

Kiro 手动 JSON 配置

将以下内容添加到您的 Kiro MCP 配置文件中（全局为 ~/.kiro/settings/mcp.json，项目范围为 .kiro/settings/mcp.json）。有关更多详细信息，请参阅 Kiro MCP 文档。

内存 DuckDB（开发模式）：

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

MotherDuck（读写）：

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

工具

工具	描述	必需输入	可选输入
`execute_query`	执行 SQL 查询（DuckDB 方言）	`sql`	-
`list_databases`	列出所有数据库（对 MotherDuck 或多个附加数据库有用）	-	-
`list_tables`	列出表和视图	-	`database`、`schema`
`list_columns`	列出表/视图的列	`table`	`database`、`schema`
`switch_database_connection`*	切换到不同的数据库	`path`	`create_if_not_exists`

*需要 --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 标志和环境变量仍然适用。

命令行参数

参数	默认值	描述
`--db-path`	`:memory:`	数据库路径：本地文件（绝对路径）、`md:`（MotherDuck）或 `s3://` URL
`--motherduck-token`	`motherduck_token` 环境变量	MotherDuck 访问令牌
`--read-write`	`False`	启用写访问
`--motherduck-saas-mode`	`False`	MotherDuck SaaS 模式（限制本地访问）
`--allow-switch-databases`	`False`	启用 `switch_database_connection` 工具
`--max-rows`	`1024`	返回的最大行数
`--max-chars`	`50000`	返回的最大字符数
`--query-timeout`	`-1`	查询超时时间（秒，-1 表示禁用）
`--init-sql`	`None`	启动时执行的 SQL
`--motherduck-connection-parameters`	`session_hint=mcp&` `dbinstance_inactivity_ttl=0s`	额外的 MotherDuck 连接字符串参数（`key=value` 对，由 `&` 分隔）
`--ephemeral-connections`	`True`	对只读本地文件使用临时连接
`--transport`	`stdio`	传输类型：`stdio` 或 `http`
`--stateless-http`	`False`	仅用于协议兼容性（例如与 AWS Bedrock AgentCore Runtime 兼容）。服务器仍然通过共享的 DatabaseClient 维护全局状态。
`--port`	`8000`	HTTP 传输的端口
`--host`	`127.0.0.1`	HTTP 传输的主机

环境变量

变量	描述
`motherduck_token` 或 `MOTHERDUCK_TOKEN`	MotherDuck 访问令牌（替代 `--motherduck-token`）
`HOME`	由 DuckDB 用于扩展和配置。如果未设置，则使用 `--home-dir` 覆盖。
`AWS_ACCESS_KEY_ID`	用于 S3 数据库连接的 AWS 访问密钥
`AWS_SECRET_ACCESS_KEY`	用于 S3 数据库连接的 AWS 秘密密钥
`AWS_SESSION_TOKEN`	用于临时凭证的 AWS 会话令牌（IAM 角色、SSO、EC2 实例配置文件）
`AWS_DEFAULT_REGION`	用于 S3 连接的 AWS 区域
`AWS_ENDPOINT`	用于 S3 连接的 AWS 端点

故障排除

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

资源

开发

从源代码运行：

{
  "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>"
      }
    }
  }
}

发布流程

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

许可证

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

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