MCP Toolbox for Databases

為什麼要用

核心特性

單一執行檔，支援多種引擎：Postgres、MySQL、BigQuery、Spanner、AlloyDB、Cloud SQL、SQLite、MSSQL、Redis、Couchbase、Dgraph、Neo4j
宣告式 tools.yaml — 每個工具都是具名的參數化陳述式，而非任意 SQL 入口
預設設定（--prebuilt postgres），零設定立即使用
連線池與驗證（IAM、OAuth、API key）集中管理，不寫在提示詞裡
Stdio 或 HTTP／SSE 傳輸 — 相容 Claude Desktop、Cursor、Codex、IDE、自訂代理
工具層級授權規則 — 限制誰能呼叫破壞性操作

即時演示

實際使用效果

mcp-toolbox-databases.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： MCP Toolbox for Databases

如何讓 Claude 安全地以唯讀方式存取正式環境 Postgres

👤 想讓 LLM 做分析但不想有資料外洩風險的後端／資料工程師 ⏱ ~25 min intermediate

何時使用： 你想讓 Claude 查詢真實資料庫，但不想要一個可以執行 DROP TABLE 的通用 execute_sql 工具。

前置條件

可透過 libpq URL 連線的 Postgres — 使用唯讀角色；永遠不要用應用程式的可寫入使用者
已安裝 Docker 或 Go — Toolbox 以單一執行檔發佈；Docker 映像最方便

步驟

使用預設 postgres 設定檔啟動 Toolbox

以 stdio 模式啟動 mcp-toolbox，使用 --prebuilt postgres，並將 POSTGRES_URL 指向唯讀副本。✓ 已複製

→ Toolbox 記錄 tools registered: list_tables, describe_table, execute_sql_readonly
接入 Claude Desktop

將 toolbox docker 設定加入 claude_desktop_config.json 的 mcpServers 區段，然後重新啟動 Claude。✓ 已複製

→ /mcp 列出 toolbox 工具，無失敗
詢問真實問題

Toolbox：列出資料表。然後針對 orders 表，過去 7 天的訂單中位值是多少？請顯示你執行的確切 SQL。✓ 已複製

→ Claude 依序呼叫 list_tables → describe_table → execute_sql_readonly，使用 SELECT（絕不使用 UPDATE／DELETE）

結果： 對真實資料進行唯讀分析，零突變風險，並留有每次查詢的稽核記錄。

注意事項

指向可寫入使用者 — Claude 最終會呼叫到修改性工具 — 務必使用僅有 GRANT SELECT 的角色；用 psql 中的 \du 驗證
在並行代理呼叫下連線池耗盡 — 在 tools.yaml 中設定 pool.max_open_conns；預設值較保守

搭配使用： filesystem · github

手寫帶有參數驗證的分析師工具

👤 不想開放原始 SQL、只允許特定查詢的團隊 ⏱ ~20 min intermediate

何時使用： 你想讓 Claude 回答「本月前 10 名客戶」，但不想讓它自行發明 JOIN 語法。

前置條件

tools.yaml 檔案 — 建立於 ~/.mcp-toolbox/tools.yaml

步驟

撰寫參數化工具

在 tools.yaml 中新增工具 top_customers：參數 since: date，陳述式為 SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ 已複製

→ Toolbox 重新載入，只暴露 top_customers — 沒有 execute_sql_readonly
從 Claude 呼叫

使用 top_customers since=2026-04-01 並解釋結果。✓ 已複製

→ 單次工具呼叫，帶有驗證後的日期參數，格式化結果

結果： 鎖定的分析師介面 — Claude 無法執行你未宣告的任何內容。

注意事項

忘記移除預設的 execute_sql 工具 — 不使用 --prebuilt；只載入你的 tools.yaml

不寫 SQL 即可探索 BigQuery 資料集

👤 使用 Google Cloud 的分析師 ⏱ ~20 min intermediate

何時使用： 你有一個 BigQuery 專案，想讓 Claude 在有成本控管的前提下回答跨資料集的問題。

前置條件

GCP 專案 + 資料集 — 執行 gcloud auth application-default login 讓 Toolbox 取得憑證

步驟

使用 --prebuilt bigquery 啟動 Toolbox

執行 toolbox --prebuilt bigquery，PROJECT=my-proj。✓ 已複製

→ 工具 bq_list_datasets、bq_dry_run、bq_query 已註冊
先執行試跑

在執行任何查詢之前，呼叫 bq_dry_run 估算掃描位元組數。若超過 1GB，請先詢問我再執行。✓ 已複製

→ 在計費查詢前顯示成本估算

結果： 帶有成本控管的 BigQuery 回答 — 不會有意外的 $200 查詢帳單。

注意事項

預設地區不符（US 與 EU） — 設定 BIGQUERY_LOCATION 環境變數

在單一 Claude 對話中查詢多個資料庫

👤 偵錯跨資料儲存問題的工程師 ⏱ ~30 min advanced

何時使用： 訂單資料在 Postgres、事件在 BigQuery、快取在 Redis — 你需要跨三者關聯。

前置條件

包含多個來源的 tools.yaml — 在 sources: 下定義每個來源，並在工具上標記來源

步驟

接入三個來源

在 tools.yaml 中新增 postgres-prod、bq-events、redis-cache 為來源。每個來源新增 1–2 個工具。✓ 已複製

→ Toolbox 啟動，所有來源標記為健康
詢問跨資料儲存問題

針對訂單 12345：從 Postgres 抓取該行資料，從 BigQuery 取得事件時間線，從 Redis 取得當前快取狀態。進行比對。✓ 已複製

→ 三個工具同時呼叫，單一連貫的回答

結果： 跨資料儲存偵錯，不需要三個獨立工具或 SSH 會話。

注意事項

來源健康檢查無聲失敗 — 啟動前執行 toolbox validate tools.yaml

搭配使用： filesystem

組合

與其他 MCP 搭配，撬動十倍槓桿

mcp-toolbox-databases + filesystem

取得查詢結果並寫入工作區的 CSV

Toolbox：本週前 100 筆訂單。Filesystem：另存為 /tmp/orders.csv。✓ 已複製

mcp-toolbox-databases + github

在 Claude 提出 schema 變更後開一個含 SQL 遷移腳本的 PR

Toolbox：描述 orders 資料表。GitHub：開一個在 customer_id 上新增索引的 PR。✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
list_tables	schema?: str	探索的第一步	1 query
describe_table	table: str	在對未知資料表寫 SQL 之前	1 query
execute_sql_readonly	sql: str	對唯讀副本進行自由格式分析	1 query
bq_dry_run	sql: str	BigQuery：永遠在 bq_query 之前呼叫	free (dry run)
bq_query	sql: str	試跑顯示成本可接受後再執行	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	你在 tools.yaml 中宣告的任何內容	1 query

成本與限制

運行它的成本

API 配額: 無 — 受限於你的資料庫連線上限
每次呼叫 Token 數: 依結果大小 100–5000
費用: 免費開源；底層資料庫／雲端照常計費
提示: 在 tools.yaml 中限制結果筆數（例如 LIMIT 200）；BigQuery 務必先走 bq_dry_run

安全

權限、密鑰、影響範圍

最小權限： 唯讀 DB 角色

憑證儲存： 環境變數或 Google ADC；Toolbox 不持久化憑證

資料出站： 直接 DB 連線 — 無第三方中轉。Toolbox 僅在本機執行。

切勿授予： DBA 在正式環境執行 DROP／TRUNCATE

正式環境務必搭配唯讀副本與唯讀角色；永遠不要使用應用程式的可寫入使用者

故障排查

常見錯誤與修復

connection refused / pool exhausted

在 tools.yaml 中增加 pool.max_open_conns；檢查 DB 連線上限

驗證： psql，執行 SELECT count(*) FROM pg_stat_activity

tool not found

若使用 --prebuilt，工具名稱例如 pg_list_tables；執行 toolbox list-tools 確認

BigQuery 403 access denied

執行 gcloud auth application-default login 並授予 roles/bigquery.dataViewer

驗證： bq ls

Spanner Cloud SDK 錯誤

將 GOOGLE_APPLICATION_CREDENTIALS 設為服務帳號 JSON

替代方案