MotherDuck

DuckDB / MotherDuck 本地 MCP 伺服器

為 AI 助理和 IDE 提供的 SQL 分析與資料工程。

使用 DuckDB 強大的分析型 SQL 引擎，將 AI 助理連接到您的資料。支援連接到本機 DuckDB 檔案、記憶體資料庫、S3 託管資料庫以及 MotherDuck。允許執行 SQL 讀取和寫入查詢、瀏覽資料庫目錄，以及即時切換不同的資料庫連線。

正在尋找 MotherDuck 的完全託管遠端 MCP 伺服器？ → 前往 MotherDuck 遠端 MCP 文件

遠端 vs 本機 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 套用安全設定。可用選項請參閱 Securing 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 文件
• Close the Loop：使用 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