DuckDB MCP 讓 AI 直接對本機 DuckDB 資料庫下 SQL,適合核對報表、探索欄位與整理資料。本文使用 MotherDuck 的開源本機伺服器,連到現有 .duckdb 檔;只要自己執行一次 SQL,就不必為此裝 MCP。
Windows 有一個容易誤判的狀況:Python 測試能連線,Codex 卻完全看不到工具。下面把 Python 輸出固定成 UTF-8,再用一份三筆訂單資料完成真正查詢。
準備範例資料庫
需要 uv 與 Codex CLI。開一個空資料夾,先建立 Python 3.12 環境並安裝:
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe mcp-server-motherduck==1.1.1
將以下程式存成 create_sales.py,只在這個空資料夾執行一次:
import duckdb
with duckdb.connect('sales.duckdb') as db:
db.execute('CREATE TABLE orders(region VARCHAR, amount INTEGER)')
db.execute("INSERT INTO orders VALUES ('Taipei',120),('Taipei',80),('Kaohsiung',50)")
.venv\Scripts\python.exe .\create_sales.py
$server = (Resolve-Path .venv\Scripts\mcp-server-motherduck.exe).Path
$db = (Resolve-Path .\sales.duckdb).Path
程式結束後再啟動 MCP,讓資料庫檔案沒有被寫入連線占用。這條路徑使用本機 DuckDB,不需要 MotherDuck 雲端帳戶。
接上 Codex 與 Claude Code
同一個 PowerShell 視窗:
codex mcp add duckdb --env PYTHONIOENCODING=utf-8 --env PYTHONUTF8=1 -- $server --db-path $db
codex mcp list
重新開啟 Codex 對話,要求使用 duckdb。可用工具應包括 list_tables、list_columns、execute_query。預設為唯讀,適合先查既有資料。
Claude Code 在專案目錄執行:
claude mcp add duckdb --scope project --transport stdio --env PYTHONIOENCODING=utf-8 --env PYTHONUTF8=1 -- $server --db-path $db
claude mcp list
健康檢查應顯示 Connected。Cursor 的設定位置與格式見官方 MCP 文件;使用相同完整執行檔路徑、--db-path 與兩個 UTF-8 環境變數。
三個可以直接問 AI 的問題
1. 先查資料有哪些欄位
只用 DuckDB MCP:先 list_tables,再 list_columns 查 orders。
列出資料表、欄位與型別,不要修改資料或猜欄位。
結果是 orders,包含 region VARCHAR、amount INTEGER。有欄位依據後再寫 SQL,可以避免 AI 猜錯欄名。
2. 核對各地區銷售額
透過 execute_query 執行 SELECT region, SUM(amount) AS total
FROM orders GROUP BY region ORDER BY total DESC。
只回報實際回傳的資料列與排序。
應得到 Taipei 200、Kaohsiung 50。兩筆 Taipei 訂單會合併為同一地區,不是把資料列數當銷售額。
3. 用總額交叉檢查分組結果
用 execute_query 執行 SELECT SUM(amount) AS total FROM orders。
核對是否等於剛才各地區加總;如果不同,先列出查詢條件差異。
總額為 250,與 200+50 相符。把兩個查詢留在回答中,比只拿到一個自然語言結論容易檢查。
Windows 連線錯誤怎麼查
Codex 沒有 DuckDB 工具,Python 卻可以連
這次實際遇到 handshaking with MCP server failed: connection closed: initialize response。伺服器啟動訊息有無法用 UTF-8 解碼的位元組;在註冊命令加入 PYTHONIOENCODING=utf-8、PYTHONUTF8=1 後,原執行檔就能完成查詢,不必修改伺服器程式。
已註冊過時,先用 codex mcp get duckdb 核對設定,再重新註冊同一個條目並開新對話。需要讓缺少連線時立即失敗,可在該伺服器的 TOML 設定加 required = true;它會揭露啟動錯誤,不會修好編碼。
Table does not exist,或欄位找不到
先查 list_tables、list_columns,並核對 $db 是剛建立的資料庫完整路徑。不要為了讓查詢通過,就在另一個空資料庫補建同名表;那樣核對的是不同資料。
寫入被拒絕
這個設定使用預設唯讀模式,CREATE、INSERT、UPDATE 等不是本文的查詢流程。要匯入資料,先在獨立的本機資料準備步驟完成,關閉寫入連線後再接 MCP。唯讀不是隔離任意 SQL 的完整安全沙箱;只連接你願意讓客戶端查詢的資料。
檔案被另一個程序鎖住
結束用來建立資料的 Python 程式或其他寫入程序,再啟動 MCP。DuckDB 的跨程序存取有條件限制,先用一個客戶端確認流程;多客戶端同時寫入不是這個範例的使用方式。
限制、費用與替代工具
本機開源伺服器採 MIT,無額外查詢費;AI 客戶端用量、選用 MotherDuck 雲端服務的費用另計。預設每次輸出最多 1024 列、50,000 字元,查大量資料應先聚合,再用 LIMIT 查看樣本。不要把回傳列數當作整張表的列數。
要自己精確寫 SQL,用 DuckDB Python 或 CLI 即可;需要讓 AI 反覆探索結構才適合 MCP。若目的是把文件交給 AI,請看 MarkItDown,它處理的是文件轉換而非 SQL。
FAQ
DuckDB MCP 一定要 MotherDuck 帳戶嗎?
本機 .duckdb 路徑不需要雲端帳戶。MotherDuck 雲端連線是同一伺服器支援的另一種資料來源,需要另外處理認證與費用。
Claude Code 和 Codex 都能用嗎?
兩者都能透過 stdio 啟動這個伺服器。使用完整執行檔與資料庫路徑,Windows 同時傳入 UTF-8 設定;Codex 要檢查實際工具呼叫,Claude Code 可先看健康檢查。
可以直接用它匯入 CSV 嗎?
本文先把資料寫進 DuckDB,再以唯讀 MCP 查詢。若要使用其他 SQL 路徑讀 CSV,需另外檢查檔案存取與讀取權限;不要以為唯讀模式會隱藏所有本機檔案。
為什麼要先查欄位再問銷售額?
自然語言問題沒有提供實際欄名、型別與單位。先取得 schema 可以避免把錯的金額欄位或文字欄位拿去加總;金額單位仍要由資料定義確認。
官方來源與我們測了什麼
MotherDuck 本機伺服器、DuckDB 並行存取、Codex MCP。查閱:2026-11-16。
Windows、Python 3.12、mcp-server-motherduck 1.1.1、DuckDB 1.5.6、FastMCP 4.2.0、Codex CLI 0.169.0。 Codex 真查表、欄位、地區 200/50 與總額 250;Claude Code add/list Connected。保存原握手失敗及 UTF-8 修復前後紀錄。 Cursor、雲端 MotherDuck、任意檔案隔離、併發寫入與大型資料集未測。