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

Neon

作者 neondatabase · neondatabase/mcp-server-neon

官方 Neon MCP — 為你的無伺服器 Postgres 建立分支以安全測試遷移、執行查詢,並從聊天中管理專案。

Neon 的官方 MCP。分支是核心功能:一秒鐘的寫時複製分支讓你在真實資料上測試破壞性遷移,完全無風險。另外還有標準的專案/角色/資料庫 CRUD 和 SQL 執行。

為什麼要用

核心特性

即時演示

實際使用效果

neon.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

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

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

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

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "neon",
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

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

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon

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

使用場景

實戰用法: Neon

在寫時複製分支上測試破壞性 Postgres 遷移

👤 針對真實資料庫執行結構描述更改的工程師 ⏱ ~20 min intermediate

何時使用: 你有一個遷移(DROP COLUMN、大型 UPDATE、索引重建),想在生產規模的資料上執行它,但不想冒險生產環境。

前置條件
  • Neon API 金鑰 — console.neon.tech → Account → API keys
步驟
  1. 從主分支建立分支
    在 Neon 專案 <id> 中,從主分支建立名為 'test-drop-legacy' 的分支。回傳新分支的連接字串。✓ 已複製
    → 分支在 <2 秒內建立,連接字串已回傳
  2. 在分支上套用遷移
    連接到新分支並執行:<貼上遷移 SQL>。回報行計數和任何錯誤。✓ 已複製
    → 遷移完成;計數合理
  3. 驗證,然後清理
    在變更的表上執行驗證查詢。如果結果看起來正確,告訴我,我會套用到主分支。無論如何,然後刪除該分支。✓ 已複製
    → 驗證 + 分支已刪除以避免儲存費用

結果: 確信你的遷移在真實資料上有效,對生產環境零風險。

注意事項
  • 分支消耗的儲存空間與你在其上寫入的量成正比 — 測試後立即刪除分支 — 有大量寫入的棄用分支會提高賬單
  • 分支是快照 — 看不到分支建立後發生在主分支上的寫入 — 分支接近套用時間;或使用 Neon 時間旅行從特定時間戳建立分支
搭配使用: github · postgres

為整合測試啟動每個 PR 的臨時資料庫

👤 針對真實 Postgres 執行 CI 整合測試的團隊 ⏱ ~15 min intermediate

何時使用: 每個 PR 需要自己的隔離資料庫;SQLite 模擬不夠。

步驟
  1. 建立以 PR 命名的分支
    在專案 <id> 中建立名為 'pr-482' 的 Neon 分支,從主分支建立。回傳連接字串。✓ 已複製
    → 分支就緒,連接字串已回傳
  2. 針對它執行測試套件
    將 DATABASE_URL 設定為該連接字串。執行 npm run test:integration 並回報結果。✓ 已複製
    → 測試執行,通過/失敗摘要
  3. 拆除
    刪除分支 'pr-482'。✓ 已複製
    → 分支已移除

結果: 真實資料庫整合測試,具有秒級啟動隔離,無共享狀態污染。

注意事項
  • 低階方案的每個專案分支限制 — 免費層限制很重要;要麼升級,要麼實施最大 N 個分支清理程式
搭配使用: github

給 Claude 安全的生產 Neon 資料庫唯讀存取

👤 不給模型寫入權力的情況下偵錯生產資料的工程師 ⏱ ~10 min beginner

何時使用: 你想調查生產問題,但擔心 UPDATE 誤發。

步驟
  1. 建立唯讀角色
    在 Neon 專案 <id> 中,建立角色 'claude_readonly',在公開結構描述上具有僅 SELECT 存取權限。回傳其連接字串。✓ 已複製
    → 角色已建立;連接字串已回傳
  2. 通過 Postgres MCP 連接
    將該連接字串與 Postgres MCP 搭配使用。確認我可以執行 SELECT 但不能 INSERT。✓ 已複製
    → SELECT 有效,INSERT 錯誤為 'permission denied'
  3. 調查問題
    現在查詢受影響 user_id 99214 的訂單表。行狀態是什麼,有什麼異常嗎?✓ 已複製
    → 來自真實資料的具體診斷

結果: 一個具有可證明唯讀安全的生產性偵錯會話。

注意事項
  • 忘記限制未來的表 — 新表未涵蓋 — 使用 ALTER DEFAULT PRIVILEGES 確保新表自動將 SELECT 授予 claude_readonly
搭配使用: postgres

在合併前跨分支審查結構描述演變

👤 DBA 和平臺工程師 ⏱ ~25 min advanced

何時使用: 多個功能分支各有自己的結構描述更改;你想看到累積差異。

步驟
  1. 列出分支及其狀態
    列出專案 <id> 的所有 Neon 分支。對於每一個,給我一行描述其結構描述如何與主分支不同。✓ 已複製
    → 每個分支結構描述差異摘要
  2. 詳細比較兩個分支
    對於分支 'feature-payments' 與主分支:比較表、欄位、索引和約束。格式化為 SQL 遷移。✓ 已複製
    → 可審查的 SQL 差異
  3. 識別衝突
    如果 feature-payments 和 feature-auth 都被合併,它們的結構描述更改會衝突嗎?在哪裡?✓ 已複製
    → 特定衝突清單,不是 'no obvious issues'

結果: 合併順序加上在合併到主分支前已知的衝突。

注意事項
  • Diff 遺漏具體化視圖或儲存程序內的更改 — 明確指定 — 要求 Claude 也比較 pg_proc 和視圖定義,不只是表
搭配使用: github

組合

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

neon + github

每個 PR 的臨時資料庫用於 CI 測試,PR 評論顯示連接資訊

當 PR #482 開啟時,建立 Neon 分支 'pr-482',針對它執行遷移 + 種子,作為 PR 上的私人評論發佈連接字串。✓ 已複製
neon + postgres

一旦 Neon 啟動分支,使用 Postgres MCP 進行更安全的唯讀查詢

建立具有唯讀角色 'claude_ro' 的 Neon 分支。然後使用 Postgres MCP 搭配該連接字串調查 user-99214 問題。✓ 已複製
neon + filesystem

按順序將本地 SQL 遷移檔案套用到 Neon 分支

按名稱順序讀取 /db/migrations/ 下的每個 .sql 檔案。按順序將它們套用到 Neon 分支 'staging'。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
list_projects none 查看你的 Neon 專案 free
describe_project project_id 取得專案概覽 free
create_branch project_id, name?, parent_id?, parent_lsn? or parent_timestamp? 為測試或每個 PR 資料庫建立分支 分支儲存按寫入計費
list_branches project_id 清點分支 free
delete_branch project_id, branch_id 測試後清理 — 重要的是控制儲存成本 free
get_connection_string project_id, branch_id?, role_name?, database_name? 取得限制於分支/角色/db 的連接字串 free
run_sql project_id, branch_id?, sql: str 針對任何分支執行 SQL 計算時間計費
describe_table_schema project_id, branch_id?, table_name 檢查表而不自己寫 SQL free
create_role / drop_role project_id, role_name 管理限制存取的角色 free
create_database / list_databases project_id, name 每個專案多資料庫設定 free

成本與限制

運行它的成本

API 配額
每個方案的標準 Neon API 限制
每次呼叫 Token 數
大多數操作很小;SQL 結果按行計數調整 — 始終限制探索性查詢
費用
MCP 免費;Neon 免費層涵蓋小專案,付費方案按計算小時數和儲存計費
提示
分支幾乎是免費的,直到它們累積寫入。#1 成本驚喜是被遺忘的分支 — 設定清理政策或始終在使用後刪除。

安全

權限、密鑰、影響範圍

最小權限: 盡可能將 API 金鑰限制到單一專案
憑證儲存: API 金鑰在環境變數 NEON_API_KEY
資料出站: 對 console.neon.tech API 的呼叫;對專案區域端點的 SQL 流量
切勿授予: 組織範圍管理金鑰給長時間執行的代理

故障排查

常見錯誤與修復

401 Unauthorized

API 金鑰無效或已撤銷。在 console.neon.tech → Account → API keys 產生新金鑰。

驗證: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects
Branch creation fails: 'limit reached'

你已達到方案的分支限制。刪除未使用的分支或升級。

run_sql times out on a long migration

長時間執行的陳述式可能超過預設逾時。對於非常長的操作,使用 psql 搭配連接字串,或分割遷移。

Connection string works once then fails (compute paused)

Neon 免費層計算自動暫停。第一個連接喚醒它(冷啟動 ~1 秒);後續連接很好。不要將第一次呼叫延遲視為失敗。

替代方案

Neon 對比其他方案

替代方案何時用它替代權衡
Supabase MCP你想要除了 Postgres 之外的身分驗證、邊緣函數、儲存更重的表面;分支限於 Pro 方案
Postgres MCP你只需要唯讀 SQL 存取且不使用分支無分支/專案管理
AWS RDS via aws MCP你在 AWS 管理的 Postgres(RDS/Aurora)上無分支;佈建更重和更慢

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

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