/ 目錄 / 演練場 / Postgres
● 官方 modelcontextprotocol 🔑 需要你的金鑰

Postgres

作者 modelcontextprotocol · modelcontextprotocol/servers

讓 Claude 以唯讀安全方式查詢你的 Postgres 資料庫,支援完整綱要自省和 EXPLAIN 計劃 — 而無需給予寫入存取權限。

Postgres MCP 伺服器參考實作。用標準 postgres:// URL 連線,提供綱要瀏覽、查詢執行和 EXPLAIN。完全唯讀 — 沒有 INSERT/UPDATE/DELETE/DDL — 適合指向正式環境的唯讀副本。

為什麼要用

核心特性

即時演示

實際使用效果

postgres.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://..."
        ]
      }
    }
  }
}

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

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://...

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

使用場景

實戰用法: Postgres

無需撰寫 SQL 就能回答臨時性的業務問題

👤 產品經理、創辦人、任何不想寫 SQL 的人 ⏱ ~10 min beginner

何時使用: 你對資料有疑問('這週有多少使用者回訪?'),但 BI 儀表板沒有答案。

前置條件
  • 副本的唯讀 postgres:// 連線字串 — 大多數託管的 PG (RDS, Neon, Supabase) 都讓你建立唯讀認證
  • 從 Claude 執行的地方到資料庫的網路存取 — VPN 或 IP 允許清單你的機器
步驟
  1. 先讓 Claude 自省相關的資料表
    列出我們資料庫中的所有資料表。針對與使用者、訂單或工作階段相關的資料表,描述它們的綱要。✓ 已複製
    → 任何查詢前的綱要概觀
  2. 提出實際問題
    過去 30 天內註冊但尚未下單的使用者有多少?按註冊週分組。✓ 已複製
    → Claude 寫 SQL、執行它、返回結果表
  3. 探測注意事項
    這個數字有可能誤導嗎?軟刪除?created_at 的時區?我們應該排除的特定使用者類型?✓ 已複製
    → 誠實地指出資料的怪異之處

結果: 業務問題的防守性答案,包含 SQL、結果和注意事項 — 2 分鐘內而非等待資料團隊 2 天。

注意事項
  • Claude 寫了一個無限制掃描你最大資料表的查詢 — 在連線上設定 statement_timeout = '30s',並在你的系統提示中加入 '預設總是包含 LIMIT 1000'
  • 計算「使用者」取決於什麼算是使用者(已刪除?機器人?測試?) — 預先告訴 Claude 你的慣例:'排除 deleted_at IS NOT NULL 的列' 等。
搭配使用: notion

診斷查詢為什麼慢並建議索引

👤 後端工程師、DBA ⏱ ~15 min intermediate

何時使用: 你有一個比應有速度更慢的查詢。你想要一雙不會疲倦於閱讀 EXPLAIN ANALYZE 輸出的眼睛。

步驟
  1. 取得查詢計劃
    在這個查詢上執行 EXPLAIN ANALYZE:[貼上]。逐步說明規劃器在做什麼。✓ 已複製
    → 逐步計劃演練
  2. 識別成本驅動力
    哪個步驟負責大部分成本?是循序掃描、不良連線順序還是昂貴的篩選?✓ 已複製
    → 識別具體節點及原因
  3. 建議索引或改寫
    建議最小的改動使其變快。偏好增加索引而非改寫查詢,但僅限於索引對超過 1 個查詢有用時。✓ 已複製
    → 具體的 CREATE INDEX 陳述式或改寫後的查詢

結果: 已索引或改寫的查詢,附帶理由,你可以再次執行 EXPLAIN 驗證。

注意事項
  • 在非代表性資料集(小型開發資料庫)上執行 EXPLAIN 會產生誤導性計劃 — 總是針對具有正式環境形狀資料的資料庫執行 EXPLAIN;否則計劃是虛構的
  • 增加索引看似免費但會減慢寫入 — 告訴 Claude 先透過 EXPLAIN 驗證索引會被使用,再要求你新增
搭配使用: sentry

稽核資料表的資料品質問題

👤 資料工程師、任何繼承陌生綱要的人 ⏱ ~25 min intermediate

何時使用: 你即將在一個你沒有設計且懷疑有問題的資料表上建置功能。

步驟
  1. 執行一系列 NULL / 重複 / 孤立檢查
    orders 資料表:計算每欄的 NULL 值數量、按某個自然鍵計算重複列(例如 (user_id, stripe_payment_intent_id))、計算外鍵指向已刪除父列的列。✓ 已複製
    → 每個檢查的問題計數
  2. 檢查值分佈異常
    total_cents 的最小值、最大值和百分位分佈是什麼?有很多可疑的 0 或負值列嗎?✓ 已複製
    → 分佈統計、異常值已標記
  3. 對照預期的業務規則進行交叉檢查
    每個『已完成』訂單應該有非空的 paid_at。有例外嗎?✓ 已複製
    → 違規計數 + 範例 ID

結果: 具體資料完整性錯誤的簡短清單,每個都有計數和修復路徑。

注意事項
  • 某些「問題」是有意的歷史遺物(資料遷移) — 在假設是錯誤之前,始終與了解歷史的人確認

為團隊自動生成綱要文件

👤 為新工程師入職的技術主管 ⏱ ~20 min beginner

何時使用: 你的資料庫有 40 個資料表,wiki 有 0 個。新員工不斷問『這個欄位是什麼?』

步驟
  1. 取得所有資料表及其綱要
    列出公開綱要中的每個資料表。對每個,給我欄位、型別、可空性、預設值和任何外鍵。✓ 已複製
    → 完整綱要傾印
  2. 從命名和範例資料推斷目的
    對每個資料表,取樣 3 列並寫一段描述這個資料表在我們業務中代表什麼。✓ 已複製
    → 每個資料表的散文說明
  3. 標記未知 / 可疑的資料表
    有任何看起來未使用或你無法推斷目的的資料表嗎?列出它們,這樣我可以詢問原始作者。✓ 已複製
    → 誠實的『我不知道這些是什麼』清單

結果: 你的團隊可以放入 Notion 或 wiki 的 Markdown 文件 — 涵蓋新員工需要知道的 80%。

注意事項
  • 將敏感資料 (PII) 取樣到 LLM 內容中 — 對於有 PII 的資料表,請求 Claude 僅描述綱要而不取樣列
搭配使用: notion · filesystem

從原始事件資料計算 A/B 測試結果

👤 產品分析師、成長工程師 ⏱ ~30 min advanced

何時使用: 你執行了實驗,資料在你的資料庫中,你想要顯著性數字而不需要手動寫 SQL。

前置條件
  • 包含實驗分派和轉換事件的事件資料表 — 標準綱要:events(user_id, experiment, variant, timestamp)、conversions(user_id, type, timestamp)
步驟
  1. 計算每個變體的轉換率
    對於實驗『checkout-redesign-2026』:多少使用者被分派到每個變體,每個變體的轉換率(按[你的轉換事件])是多少?✓ 已複製
    → 包含速率的每個變體表
  2. 計算統計顯著性
    計算對照組和處理組之間差異的卡方 p 值。結果在 p < 0.05 時統計上顯著嗎?✓ 已複製
    → p 值及判決
  3. 合理性檢查數字
    樣本大小是否平衡?實驗執行足夠長嗎?有任何結果反轉的區段嗎?✓ 已複製
    → 健康檢查,不只是 p 值

結果: 統計上防守性的 A/B 測試報告,包含 SQL、數字和注意事項。

注意事項
  • 在預定義樣本大小前檢視結果導致假陽性 — 讓 Claude 在計算顯著性前檢查測試是否達到目標樣本大小
搭配使用: notion

組合

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

postgres + notion

執行查詢,將結果作為 Notion 表發佈給沒有資料庫存取權限的利益相關者

查詢本季度按終身收入計算的前 10 名客戶,然後在『銷售報告』中建立 Notion 頁面,並將結果格式化為表格。✓ 已複製
postgres + sentry

將資料庫狀態與錯誤交叉參照 — 當錯誤提到記錄 ID 時,查詢它

Sentry 問題 WEB-3a91 提及 order_id 99214。查詢該訂單並告訴我列資料中是否有任何內容可以解釋崩潰。✓ 已複製
postgres + filesystem

匯出查詢結果為 CSV/JSON 供下游使用

執行我的流失世代查詢並將結果儲存為 /reports/churn-2026-04.csv。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
list_tables schema?: str 任何工作階段的第一步 — 發現綱要 free
describe_table table: str, schema?: str 在查詢前取得特定資料表的完整結構 free
query sql: str 執行任何唯讀 SQL — 僅限 SELECT depends on query

成本與限制

運行它的成本

API 配額
受你的資料庫連線限制和查詢逾時的限制
每次呼叫 Token 數
綱要查詢:~500 個權杖。結果集:取決於列計數 — 以 LIMIT 上限
費用
免費 — 成本就是你的資料庫託管帳單已經是什麼
提示
始終在連線上設定 statement_timeout(例如 ?options=-c%20statement_timeout%3D30000),以防止失控查詢推倒你的資料庫。

安全

權限、密鑰、影響範圍

最小權限: SELECT 在你想暴露的資料表上
憑證儲存: 連線字串在環境變數中。使用專用的唯讀角色:CREATE ROLE claude_readonly LOGIN PASSWORD '...'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
資料出站: 所有對你資料庫的查詢;結果列運送到你使用的任何 LLM 提供者
切勿授予: INSERT UPDATE DELETE DROP TRUNCATE ALTER

故障排查

常見錯誤與修復

FATAL: password authentication failed

檢查連線字串。常見原因:密碼中的特殊字元未進行 URL 編碼。

驗證: psql 'postgres://...' -c 'SELECT 1'
no pg_hba.conf entry / SSL required

在連線字串附加 ?sslmode=require。大多數託管的 Postgres 需要 SSL。

permission denied for table X

該角色在該資料表上沒有 SELECT 權限。執行 GRANT SELECT ON X TO claude_readonly

驗證: psql -c '\dp X'
canceling statement due to statement timeout

查詢太慢。要麼優化它(增加索引、縮小 WHERE 子句),要麼為該連線提高逾時。

替代方案

Postgres 對比其他方案

替代方案何時用它替代權衡
Supabase MCP你在 Supabase 上 — 取得完整專案管理加 SQL包含寫入存取;對於正式環境較不安全
Neon MCP你在 Neon 上 — 增加用於安全遷移測試的分支Neon 特定功能僅適用於 Neon 資料庫
dbHub你需要在一個 MCP 中支援多個資料庫(Postgres、MySQL、MongoDB 等)較新;支援更多資料庫但每個整合較不深入
sqlite MCP本地檔案型資料庫而非伺服器沒有並行存取、沒有網路,但零設定

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills