MotherDuck MCP Server

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:。若要使用 MotherDuck，請明確加入 --db-path md:。
• 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 套件）
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 指南。

命令列參數

環境變數

疑難排解

• 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