Neon MCP Server | Awesome MCP Servers

Neon MCP 伺服器

Neon MCP 伺服器 是一款開源工具，讓您能以自然語言與 Neon Postgres 資料庫互動。

模型上下文協定 (MCP) 是一個標準化協定，旨在管理大型語言模型 (LLM) 與外部系統之間的上下文。此儲存庫為 Neon 提供了一個遠端 MCP 伺服器。

Neon 的 MCP 伺服器扮演著自然語言請求與 Neon API 之間的橋樑。它建立在 MCP 之上，將您的請求轉換為必要的 API 呼叫，讓您能夠無縫地管理諸如建立專案和分支、執行查詢以及執行資料庫遷移等任務。

Neon MCP 伺服器的一些主要功能包括：

自然語言互動： 使用直覺的對話式指令管理 Neon 資料庫。
簡化的資料庫管理： 無需編寫 SQL 或直接使用 Neon API 即可執行複雜操作。
非開發人員的可用性： 讓具備不同技術背景的使用者都能與 Neon 資料庫互動。
資料庫遷移支援： 利用 Neon 的分支功能，透過自然語言啟動資料庫結構描述變更。

例如，在 Claude Code 或任何 MCP 用戶端中，您可以使用自然語言來完成與 Neon 相關的工作，例如：

Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Neon MCP 伺服器安全考量
Neon MCP 伺服器透過自然語言請求授予強大的資料庫管理能力。在執行前，務必審查並授權 LLM 請求的操作。 確保只有授權的使用者和應用程式可以存取 Neon MCP 伺服器。

Neon MCP 伺服器僅適用於本機開發和 IDE 整合。我們不建議在生產環境中使用 Neon MCP 伺服器。 它可能執行強大的操作，導致意外或未經授權的變更。

如需更多資訊，請參閱 MCP 安全指引 →。

設定 Neon MCP 伺服器

設定 Neon MCP 伺服器有幾種選項：

使用 API 金鑰快速設定 (Cursor、VS Code 和 Claude Code)： 執行 neonctl@latest init 以透過一個指令自動設定 Neon 的 MCP 伺服器、代理技能和 VS Code 擴充功能。
遠端 MCP 伺服器 (基於 OAuth 的驗證)： 使用 OAuth 進行驗證，連接到 Neon 的託管 MCP 伺服器。此方法更為方便，因為無需管理 API 金鑰。此外，您將在最新功能和改進發布時自動獲得它們。
遠端 MCP 伺服器 (基於 API 金鑰的驗證)： 使用 API 金鑰進行驗證，連接到 Neon 的託管 MCP 伺服器。如果您想將遠端代理連接到無法使用 OAuth 的 Neon，此方法很有用。此外，您將在最新功能和改進發布時自動獲得它們。

先決條件

一個 MCP 用戶端應用程式。
一個 Neon 帳戶。
Node.js (>= v18.0.0)： 從 nodejs.org 下載。

對於開發，您需要 Node.js 22+ (pnpm 透過 Corepack 提供 — 執行 corepack enable 來啟用它)。

選項 1. 使用 API 金鑰快速設定

不想手動建立 API 金鑰嗎？

執行 neonctl@latest init 以透過一個指令自動設定 Neon 的 MCP 伺服器：

npx neonctl@latest init

這適用於 Cursor、VS Code (GitHub Copilot) 和 Claude Code。它將透過 OAuth 進行驗證，為您建立一個 Neon API 金鑰，並自動設定您的編輯器。

選項 2. 遠端託管 MCP 伺服器 (基於 OAuth 的驗證)

使用 OAuth 進行驗證，連接到 Neon 的託管 MCP 伺服器。這是最簡單的設定，無需在本機安裝此伺服器，也不需要在此用戶端中設定 Neon API 金鑰。

執行以下指令，為您工作區中所有偵測到的代理和編輯器新增 Neon MCP 伺服器：

npx add-mcp https://mcp.neon.tech/mcp

新增 -g 旗標，將 Neon MCP 伺服器新增到全域 MCP 伺服器清單，而非專案範圍。

或者，您可以將以下 "Neon" 項目新增到您用戶端的 MCP 伺服器設定檔中 (例如，mcp.json、mcp_config.json)：

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro： 將以下內容新增到您的 Kiro MCP 設定檔中 (全域為 ~/.kiro/settings/mcp.json，或專案範圍為 .kiro/settings/mcp.json)：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

或使用本 README 頂部的一鍵安裝按鈕。如需更多資訊，請參閱 Kiro MCP 文件。

重新啟動或重新整理您的 MCP 用戶端。
一個 OAuth 視窗將在您的瀏覽器中開啟。按照提示授權您的 MCP 用戶端存取您的 Neon 帳戶。

使用基於 OAuth 的驗證時，MCP 伺服器預設將對您個人 Neon 帳戶下的專案進行操作。若要存取或管理屬於組織的專案，您必須在給 MCP 用戶端的提示中明確提供 org_id 或 project_id。

選項 3. 遠端託管 MCP 伺服器 (基於 API 金鑰的驗證)

如果您的用戶端支援，遠端 MCP 伺服器也支援在 Authorization 標頭中使用 API 金鑰進行驗證。

在 Neon 主控台中建立一個 Neon API 金鑰。接下來，執行以下指令，為您工作區中所有偵測到的代理和編輯器新增 Neon MCP 伺服器：

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

或者，您可以將以下 "Neon" 項目新增到您用戶端的 MCP 伺服器設定檔中 (例如，mcp.json、mcp_config.json)：

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

提供組織的 API 金鑰，以將存取權限限制在該組織下的專案。

範圍和唯讀模式

Neon MCP 支援 OAuth 範圍 read、write 和 * (* 表示兩者)。您的 MCP 用戶端可以直接請求這些範圍，或者您可以在 OAuth 權限 UI 中進行選擇。

唯讀模式 會限制可用的工具，停用諸如建立專案、分支或執行遷移等寫入操作。唯讀工具包括列出專案、描述結構描述、查詢資料和檢視效能指標。

您可以透過兩種方式設定唯讀模式：

OAuth 範圍選擇 (建議)： 在 OAuth 中，透過在授權 UI 中取消勾選 完整存取權 來選擇唯讀。
readonly 查詢參數： 將 ?readonly=true 新增到您的 MCP 伺服器 URL：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

查詢參數的行為方式：

API 金鑰流程： readonly=true 是啟用唯讀模式的方式 (此流程中沒有 OAuth 範圍交換)。
OAuth 流程： readonly=true 會覆蓋 OAuth 範圍。如果沒有它，唯讀與否取決於在 OAuth 同意 UI 中選擇的範圍。

舊版的 HTTP 標頭 x-read-only 也作為備用方案受到支援 (優先級低於查詢參數)。

注意： 唯讀模式會限制哪些工具可用。此外，run_sql 工具僅對唯讀查詢保持可用。

用於存取控制的 URL 查詢參數

授予上下文 (範圍類別、專案範圍界定、唯讀模式) 是透過 MCP 伺服器 URL 上的 URL 查詢參數來設定的。設定會隨著每個請求傳送並立即生效 — 無需重新驗證。

參數	說明	範例
`readonly`	啟用唯讀模式 (`true`/`false`)	`?readonly=true`
`category`	限制為特定的工具類別 (可重複或 CSV)	`?category=querying&category=schema`
`projectId`	將所有操作範圍限定在單一專案	`?projectId=proj-123`

唯讀 + 專案範圍範例：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

類別篩選範例 (僅查詢和結構描述工具)：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

您可以使用 /api/list-tools 端點 (無需驗證) 預覽任何設定下可見的工具：

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

唯讀模式下可用的工具

list_projects、list_shared_projects、describe_project、list_organizations
describe_branch、list_branch_computes、compare_database_schema
run_sql、run_sql_transaction、get_database_tables、describe_table_schema
list_slow_queries、explain_sql_statement
get_connection_string
search、fetch、list_docs_resources、get_doc_resource

需要寫入存取權的工具：

create_project、delete_project
create_branch、delete_branch、reset_from_parent
provision_neon_auth、provision_neon_data_api
prepare_database_migration、complete_database_migration
prepare_query_tuning、complete_query_tuning

伺服器傳送事件 (SSE) 傳輸 (已棄用)

MCP 支援兩種遠端伺服器傳輸：已棄用的伺服器傳送事件 (SSE) 和較新且推薦的可串流 HTTP。如果您的 LLM 用戶端尚不支援可串流 HTTP，您可以將端點從 https://mcp.neon.tech/mcp 切換到 https://mcp.neon.tech/sse 以改用 SSE。

執行以下指令，使用 SSE 傳輸為您工作區中所有偵測到的代理和編輯器新增 Neon MCP 伺服器：

npx add-mcp https://mcp.neon.tech/sse --type sse

遠端伺服器架構

遠端伺服器在 Vercel 上作為 Next.js App Router 應用程式執行，位於 mcp.neon.tech。

[!NOTE] 根路徑 / 會重新導向到 Neon MCP 伺服器文件。沒有登陸頁面。

核心實作區域：

landing/app/api/[transport]/route.ts：用於可串流 HTTP (/mcp) 和 SSE (/sse) 的 MCP 傳輸端點
landing/app/api/authorize/、landing/app/callback/、landing/app/api/token/、landing/app/api/revoke/：OAuth 流程端點
landing/app/.well-known/：OAuth 探索中繼資料端點
landing/mcp-src/：MCP 伺服器、工具、處理常式、分析和 Sentry 整合
landing/lib/：與 Next.js 相容的輔助工具 (OAuth、設定、錯誤處理)
landing/mcp-src/utils/read-only.ts：唯讀模式和範圍處理

指南

功能

支援的工具

Neon MCP 伺服器提供以下操作，這些操作作為「工具」公開給 MCP 用戶端。您可以使用這些工具，透過自然語言指令與您的 Neon 專案和資料庫互動。

工具範圍中繼資料

每個工具定義都包含一個 scope 類別，用於基於授權的工具篩選和同意 UX。目前的類別有：

projects
branches
schema
querying
neon_auth
data_api
docs
null (沒有範圍類別的工具)

注意事項：

compare_database_schema 歸類在 schema 下。
provision_neon_data_api 歸類在 data_api 下 (與 neon_auth 分開)。
唯讀強制執行仍然依賴 readOnlySafe 和伺服器端的唯讀邏輯；scope 是類別中繼資料，而非獨立的讀/寫開關。
在專案範圍模式 (?projectId=...) 下，search 和 fetch 不可用。

專案管理：

list_projects：列出您帳戶中的前 10 個 Neon 專案，提供每個專案的摘要。若找不到特定專案，可傳遞較高的值給 limit 參數來增加數量上限。
list_shared_projects：列出與目前使用者共用的 Neon 專案。支援搜尋參數，並可限制回傳的專案數量（預設：10）。
describe_project：擷取特定 Neon 專案的詳細資訊，包括其 ID、名稱，以及關聯的分支和資料庫。
create_project：在您的 Neon 帳戶中建立新的 Neon 專案。專案可作為分支、資料庫、角色和計算資源的容器。
delete_project：刪除現有的 Neon 專案及其所有相關資源。
list_organizations：列出目前使用者有權存取的所有組織。可選擇使用搜尋參數，依組織名稱或 ID 進行篩選。

分支管理：

create_branch：在指定的 Neon 專案中建立新分支。利用 Neon 的分支功能進行開發、測試或遷移。
delete_branch：從 Neon 專案中刪除現有分支。
describe_branch：擷取特定分支的詳細資訊，例如其名稱、ID 和父分支。
list_branch_computes：列出專案或特定分支的計算端點，包括計算 ID、類型、大小、最後活動時間和自動擴展資訊。
compare_database_schema：顯示子分支與其父分支之間的結構描述差異。
reset_from_parent：將目前分支重設為其父分支的狀態，捨棄本機變更。若分支有子分支，會自動保留為備份，或可依要求選擇以自訂名稱保留。

SQL 查詢執行：

get_connection_string：回傳您的資料庫連線字串。
run_sql：對指定的 Neon 資料庫執行單一 SQL 查詢。支援讀取和寫入操作。
run_sql_transaction：在單一交易中對 Neon 資料庫執行一系列 SQL 查詢。
get_database_tables：列出指定 Neon 資料庫中的所有資料表。
describe_table_schema：擷取特定資料表的結構描述定義，詳細說明欄位、資料類型和約束條件。

資料庫遷移（結構描述變更）：

prepare_database_migration：啟動資料庫遷移程序。關鍵的是，它會建立一個臨時分支，以便在影響主分支之前安全地套用和測試遷移。
complete_database_migration：完成並將已準備好的資料庫遷移套用至主分支。此操作會合併來自臨時遷移分支的變更，並清理臨時資源。

SQL 查詢與最佳化：

list_slow_queries：透過找出資料庫中最慢的查詢來識別效能瓶頸。需要 pg_stat_statements 擴充功能。
explain_sql_statement：提供 SQL 查詢的詳細執行計畫，協助識別效能瓶頸。
prepare_query_tuning：分析查詢效能並建議最佳化方式，例如建立索引。建立臨時分支以安全地測試這些最佳化。
complete_query_tuning：透過將最佳化套用至主分支或捨棄它們，來完成查詢調校。清理臨時調校分支。

Neon Auth：

provision_neon_auth：為 Neon 專案配置 Neon Auth。它允許開發者透過與驗證提供者建立整合，輕鬆設定驗證基礎架構。

Neon Data API：

provision_neon_data_api：配置 Neon Data API，以實現基於 HTTP 的資料庫存取，並可選擇透過 Neon Auth 或外部 JWKS 提供者進行 JWT 驗證。

搜尋與探索：

search：搜尋符合查詢條件的組織、專案和分支。回傳 ID、標題和 Neon 主控台的直接連結。
fetch：使用 ID（通常來自搜尋工具）擷取特定組織、專案或分支的詳細資訊。

文件與資源：

list_docs_resources：透過從 https://neon.com/docs/llms.txt 擷取索引，列出所有可用的 Neon 文件頁面。回傳頁面 URL 和標題，可使用 get_doc_resource 工具個別擷取。
get_doc_resource：以 Markdown 內容擷取特定的 Neon 文件頁面。請先使用 list_docs_resources 工具探索可用的頁面 slug，然後將 slug 傳遞給此工具。

遷移

遷移是一種隨著時間管理資料庫結構描述變更的方式。透過 Neon MCP 伺服器，LLM 能夠使用獨立的「開始」（prepare_database_migration）和「提交」（complete_database_migration）指令安全地進行遷移。

「開始」指令接受一個遷移，並在新的臨時分支中執行它。回傳時，此指令會提示 LLM 應在此分支上測試遷移。然後，LLM 可以執行「提交」指令，將遷移套用至原始分支。

開發

此專案使用 pnpm 作為套件管理器，並透過 Corepack 固定版本。

專案結構

MCP 伺服器程式碼位於 landing/ 目錄中，這是一個部署在 Vercel 上（網址為 mcp.neon.tech）的 Next.js 應用程式。

cd landing
corepack enable
pnpm install

本機開發

# Start the Next.js dev server (for the remote MCP server)
pnpm run dev

程式碼檢查與型別檢查

pnpm run lint
pnpm run typecheck

環境變數

遠端伺服器執行階段所需：

變數	說明
`SERVER_HOST`	伺服器 URL（預設為 `VERCEL_URL`）
`UPSTREAM_OAUTH_HOST`	Neon OAuth 提供者 URL
`CLIENT_ID`	OAuth 用戶端 ID
`CLIENT_SECRET`	OAuth 用戶端密鑰
`COOKIE_SECRET`	用於簽署 Cookie 的密鑰
`KV_URL`	Vercel KV（Upstash Redis）URL
`OAUTH_DATABASE_URL`	用於權杖儲存的 Postgres URL

選用：

變數	說明
`LOG_LEVEL`	Winston 日誌層級：`error`、`warn`、`info`（預設）、`debug`、`verbose`、`silly`

測試金字塔

所有測試均從 landing/ 執行。

cd landing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm run test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm run test:e2e:web

# Full end-to-end suite
pnpm run test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm run test

測試策略：

偏好使用 E2E 測試來處理傳輸/協定和使用者可見的行為。
使用整合測試來處理確定性的工具合約和工作流程行為。
使用單元測試來處理純邏輯和邊緣案例。
避免在合併閘控測試中依賴第三方服務的可用性；在整合/單元層級模擬外部相依項。

部署

Vercel 會根據儲存庫分支設定自動部署遠端伺服器。提取請求（Pull Request）可使用預覽環境。