Neon

官方

與 Neon 無伺服器 Postgres 平台互動

GitHub

629

試用此 MCP贊助

你可以用 Neon MCP 做什麼？

建立與管理專案 — 要求建立新的 Postgres 資料庫專案、列出既有專案，或透過 create_project、list_projects 和 delete_project 刪除專案。
分支與結構描述操作 — 使用 create_branch、reset_from_parent 和 compare_database_schema 建立開發分支、重設至父層 HEAD，或比較分支之間的結構描述。
執行 SQL 與檢查資料 — 使用 run_sql、run_sql_transaction、get_database_tables 和 describe_table_schema 執行單一查詢或交易、列出資料表，並描述結構描述。
安全地遷移結構描述 — 在暫時分支上開始遷移、進行測試，然後透過 prepare_database_migration 和 complete_database_migration 將其提交至主分支。
診斷與調整效能 — 使用 list_slow_queries、explain_sql_statement 和 prepare_query_tuning 找出慢查詢、取得執行計畫，並在暫時分支上測試最佳化。
搜尋與擷取資源 — 尋找組織、專案或分支並擷取詳細資料，或使用 search、fetch、list_docs_resources 和 get_doc_resource 拉取 Neon 文件頁面。

文件

Neon MCP 伺服器

Neon MCP 伺服器 是一個開放原始碼工具，可讓您以自然語言與 Neon 上的 Lakebase 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）： 執行 neon@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 下載。
如果啟用了 IP 允許清單，請將 34.192.103.46 和 23.22.233.166 新增到您的允許清單中（mcp.neon.tech 靜態 IP）。

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

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

不想手動建立 API 金鑰？

執行 neon@latest init 以一條指令自動設定 Neon 的 MCP 伺服器：

npx neon@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?category=projects&category=branches&category=endpoints&category=querying&category=schema"

該 URL 發布專案、分支、計算端點、查詢和結構。使用 /api/list-tools?category=projects&category=branches&category=endpoints&category=querying&category=schema 預覽它。未過濾的 URL 發布所有類別：

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?category=projects&category=branches&category=endpoints&category=querying&category=schema"
    }
  }
}

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

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

或者使用此 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?category=projects&category=branches&category=endpoints&category=querying&category=schema" --header "Authorization: Bearer <$NEON_API_KEY>"

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

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

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

範圍與唯讀模式

Neon MCP 宣告 OAuth 範圍 read 和 write。您的 MCP 用戶端可以請求這些範圍，或者您可以在 OAuth 權限 UI 中進行選擇。如果用戶端仍傳送 *，則將其視為寫入。

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

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

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

{
  "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 上的查詢參數設定。設定會隨每個請求傳送並立即生效 — 無需重新驗證。

參數	描述	範例
`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_organizations、describe_branch、run_sql、run_sql_transaction、get_database_tables、describe_table_schema、list_slow_queries、explain_sql_statement、inspect_database、get_neon_auth_config、search、fetch、list_docs_resources、get_doc_resource。

產生的 Management API 工具中屬於 GET 且不傳回機密的工具，加上 query_logs（POST，唯讀）。使用 /api/list-tools?readonly=true 預覽確切集合。

需要寫入存取權的工具：

產生的 Management API 寫入（create_project、create_branch、delete_project、…）
get_connection_string（連線字串帶有特權角色密碼，因此在唯讀模式下會隱藏；請改從 Neon 主控台複製）
prepare_database_migration、complete_database_migration
prepare_query_tuning、complete_query_tuning

伺服器傳送事件（SSE）傳輸（已棄用）

MCP 支援兩種遠端伺服器傳輸：已棄用的伺服器傳送事件（SSE）和較新的、建議使用的 Streamable HTTP。如果您的 LLM 用戶端尚不支援 Streamable 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 伺服器文件。沒有登陸頁面。

核心實作領域：

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

指南

功能

支援的工具

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

工具範圍中繼資料

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

projects
branches
endpoints
snapshots
schema
querying
neon_auth
data_api
observability
docs
functions
storage
null（無範圍類別的工具）

備註：

Management API 工具來自 @neon/tools。選擇器是 SDK 路徑（projects.list）；已發布的 MCP 名稱是動詞優先（list_projects、delete_project、query_logs）。歷史名稱保留在原本存在的位置（describe_project、create_branch、reset_from_parent、compare_database_schema、provision_neon_auth、provision_neon_data_api、list_branch_computes）。
?category=branches 包含分支、角色和資料庫工具（list_postgres_roles、create_postgres_database、…）。已為 branches 發出的權杖會獲得這些寫入權限。計算列表是 ?category=endpoints。快照還原是 ?category=snapshots。
專案成員和權限寫入未發布。list_project_members 和 list_project_permissions 是唯讀。
Schema 工具（?category=schema）是主機工具 get_database_tables 和 describe_table_schema，加上產生的 compare_database_schema。
唯讀強制執行仍依賴 readOnlySafe 和伺服器端唯讀邏輯；scope 是類別元資料，不是獨立的讀寫開關。
在專案範圍模式（?projectId=...）下，沒有專案路徑的工具（list_projects、create_project、list_organizations、list_regions、search、fetch、…）會被隱藏。delete_project 也會被隱藏。

專案管理：

list_projects：列出 Neon 專案。limit 限制回傳的項目數量。
describe_project：依 id（{ "project_id": "…" }）取得 Neon 專案。
create_project：建立 Neon 專案並等待預設計算端點就緒。不回傳連線字串。引數為 { "name": "…", "org_id": "…", "region_id": "…" }。成功後呼叫 get_connection_string。
delete_project：刪除現有的 Neon 專案。引數為 { "project_id": "…" }。
list_organizations：列出目前使用者有權存取的所有組織。可選擇使用搜尋參數依組織名稱或 ID 篩選。

分支管理：

list_branches：列出專案中的分支。用它將分支名稱解析為 br-… id。
create_branch：建立一個帶有讀寫計算端點的分支，並等待其就緒。不回傳連線字串。引數為 { "project_id": "…", "name": "feature-x" }。傳入 no_compute: true 以跳過端點。成功後呼叫 get_connection_string。
reset_from_parent：將分支重設為其父分支目前的 HEAD（{ "project_id": "…", "branch_id": "br-…" }）。捨棄分支分歧以來的寫入。當分支有子分支時，preserve_under_name 為必填；這些子分支會移到新分支。僅限父分支 HEAD；時間點還原是 restore_snapshot。
delete_branch：刪除分支（{ "project_id": "…", "branch_id": "br-…" }）。
describe_branch：取得分支上的資料庫、schema、資料表、檢視和函式樹狀結構。
產生的分支工具接受 branch_id 作為分支 id（br-...），而非名稱。
restore_snapshot：還原快照。傳入 target_branch_id 以還原到現有分支；省略則建立新分支。

計算端點（?category=endpoints）：

list_postgres_endpoints、list_branch_computes、get_postgres_endpoint、create_postgres_endpoint、update_postgres_endpoint、delete_postgres_endpoint、start_postgres_endpoint、suspend_postgres_endpoint、restart_postgres_endpoint

快照（?category=snapshots）：

list_snapshots、get_snapshot_schedule、set_snapshot_schedule、create_snapshot、update_snapshot、delete_snapshot、restore_snapshot

Schema（?category=schema）：

get_database_tables、describe_table_schema
compare_database_schema：一個資料庫對另一個分支的 SQL schema 差異。database_name 為必填。省略 base_branch_id 則與父分支比較。選用的 lsn、timestamp、base_lsn、base_timestamp 僅限時間點。

SQL 查詢執行：

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

資料庫遷移（Schema 變更）：

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

SQL 查詢與最佳化：

inspect_database：對分支執行 15 個預先定義的唯讀 Postgres 診斷之一——關聯和索引大小、索引和循序掃描使用情況、作用中查詢和鎖定、最重和最頻繁的查詢、快取命中率和工作集大小、autovacuum 和膨脹估計，以及複製狀態。與 neon inspect db CLI 命令相同的檢查。省略 database_name 以涵蓋分支上的所有資料庫；傳入名稱以檢查單一資料庫。其中四個需要 pg_stat_statements 或 neon 擴充功能。
list_slow_queries：透過找出資料庫中最慢的查詢來識別效能瓶頸。需要 pg_stat_statements 擴充功能。
explain_sql_statement：提供 SQL 查詢的詳細執行計畫，以協助識別效能瓶頸。
prepare_query_tuning：分析查詢效能並建議最佳化，例如建立索引。建立臨時分支以安全地測試這些最佳化。
complete_query_tuning：透過將最佳化套用到主分支或捨棄它們來完成查詢調校。清理臨時調校分支。

Neon Auth（?category=neon_auth）：

provision_neon_auth、get_auth、disable_auth、update_auth_config
get_neon_auth_config：主機工具；機密已編輯。使用產生的 Auth 寫入工具來變更設定。
list_auth_oauth_providers、add_auth_oauth_provider、update_auth_oauth_provider、delete_auth_oauth_provider
list_auth_trusted_domains、add_auth_trusted_domain、delete_auth_trusted_domain
create_auth_user、delete_auth_user、update_auth_user_role

Neon Data API（?category=data_api）：

provision_neon_data_api、get_data_api、update_data_api、delete_data_api：管理分支資料庫的 Data API。

搜尋與探索：

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

可觀測性（?category=observability）：這些工具需要 Neon Platform Beta，目前僅適用於 aws-us-east-2 區域的專案。沒有日誌存取權限的分支會回傳 HTTP 404，原因為 telemetry_not_enabled。

query_logs：查詢分支的 OpenTelemetry 日誌。Management API 中的 POST；此伺服器將其視為唯讀。
list_log_fields：列出您可以在分支上列舉值的日誌欄位。
list_log_field_values：列出分支和時間視窗內日誌欄位的相異值。

文件與資源（?category=docs）：

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

函式（?category=functions）：

list_functions、get_function、update_function、delete_function、deploy_function
list_functions_custom_domains、register_functions_custom_domain、delete_functions_custom_domain

儲存（?category=storage）：

list_storage_buckets、create_storage_bucket、delete_storage_bucket
list_storage_objects、delete_storage_object、delete_storage_objects_by_prefix
presign_storage_object、get_storage

遷移

遷移是一種隨時間管理資料庫 schema 變更的方式。使用 Neon MCP 伺服器，LLM 可以透過分開的「開始」（prepare_database_migration）和「提交」（complete_database_migration）命令安全地進行遷移。

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

開發

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

專案結構

MCP 伺服器程式碼位於儲存庫根目錄，這是一個部署到 Vercel 的 Next.js 應用程式，位於 mcp.neon.tech。

corepack enable
pnpm install

請參閱 CONTRIBUTING.md 了解如何新增工具。工具引數為 snake_case。

本機開發

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

Linting 和型別檢查

pnpm lint
pnpm typecheck

環境變數

遠端伺服器執行時期所需：

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

選用：

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

測試金字塔

所有測試都從儲存庫根目錄執行。

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

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

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

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

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

測試策略：

偏好端對端測試來驗證傳輸/協定和使用者可見行為。
使用整合測試來驗證確定性的工具契約和工作流程行為。
使用單元測試來驗證純邏輯和邊緣案例。
避免在合併閘道測試中依賴第三方正常運行時間；在整合/單元層級模擬外部依賴。

部署

Vercel 會根據儲存庫分支設定自動部署遠端伺服器。預覽環境可用於拉取請求。