MotherDuck

官方

使用 MotherDuck 和本地 DuckDB 查詢與分析資料

GitHub

505

你可以用 Mother Duck MCP 做什麼？

對 DuckDB 或 MotherDuck 執行 SQL 查詢 — 請您的助理透過 execute_query 執行分析型 SQL，支援讀取及選擇性寫入操作。
探索資料庫結構 — 使用 list_databases 列出可用的資料庫，接著使用 list_tables 和 list_columns 深入檢視資料表與欄位。
切換資料庫連線 — 使用 switch_database_connection 在執行期間於本機 DuckDB 檔案、記憶體執行個體、S3 託管資料庫或 MotherDuck 之間切換。
連線至 MotherDuck 進行雲端分析 — 將伺服器指向帶有 token 的 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:。若要使用 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 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： 複製此儲存庫並根據需要自訂。使用**服務帳戶搭配讀取擴展權杖，並啟用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 旗標和環境變數仍然適用。

命令列參數

參數	預設值	說明
`--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