Neon

官方

與 Neon 無伺服器 Postgres 平台互動

你可以用 Neon MCP 做什麼？

建立專案和分支 — 請助理建立新的 Postgres 資料庫或名為 feature-x 的分支，並等待其運算資源就緒。
執行 SQL 和交易 — 在選定的 Neon 資料庫中執行單一查詢，或在單一交易中執行一系列陳述式。
檢視結構描述和資料表 — 列出資料庫中的資料表、查看資料表的欄位和限制條件，或比較不同分支的結構描述。
安全地測試遷移 — 在暫存分支上準備結構描述變更，然後完成變更，將遷移套用至主要分支。
調校緩慢查詢 — 找出緩慢的查詢、取得執行計畫，並在暫存分支上測試建議的最佳化方式，例如建立索引。
摘要專案資訊 — 列出 Neon 專案和組織，或搜尋各個專案和分支，以尋找 ID 和主控台連結。

託管 MCP 伺服器

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

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

Neon MCP Server

Neon MCP Server 是一款開放原始碼工具，讓您能以自然語言與 Neon 上的 Lakebase Postgres 資料庫互動。

模型上下文協定（MCP）是一種標準化協定，旨在管理大型語言模型（LLM）與外部系統之間的上下文。此儲存庫提供適用於 Neon 的遠端 MCP Server。

Neon 的 MCP Server 是自然語言請求與 Neon API 之間的橋樑。它以 MCP 為基礎，將您的請求轉換為必要的 API 呼叫，讓您能順暢地管理建立專案和分支、執行查詢及進行資料庫遷移等工作。

Neon MCP Server 的主要功能包括：

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

例如，在 Claude Code 或任何 MCP Client 中，您可以使用自然語言完成 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 Server 安全性注意事項
Neon MCP Server 可透過自然語言請求執行強大的資料庫管理操作。執行前，請務必檢查並授權 LLM 要求的操作。 確保只有獲授權的使用者和應用程式能存取 Neon MCP Server。

Neon MCP Server 僅供本機開發和 IDE 整合使用。我們不建議在正式環境中使用 Neon MCP Server。 它可以執行強大的操作，可能導致意外或未經授權的變更。

如需詳細資訊，請參閱 MCP 安全性指南 →。

設定 Neon MCP Server

設定 Neon MCP Server 有幾種方式：

使用 API Key 快速設定（Cursor、VS Code 和 Claude Code）： 執行 neon@latest init，即可透過一個指令自動設定 Neon MCP Server、agent skills 和 VS Code 擴充功能。
遠端 MCP Server（以 OAuth 驗證）： 使用 OAuth 驗證連線至 Neon 託管的 MCP Server。此方法更方便，因為不必管理 API Key。此外，您會在最新功能和改進推出後立即自動取得。
遠端 MCP Server（以 API Key 驗證）： 使用 API Key 驗證連線至 Neon 託管的 MCP Server。如果您想在 OAuth 不可用時將遠端代理程式連線至 Neon，此方法就很實用。此外，您會在最新功能和改進推出後立即自動取得。

先決條件

MCP Client 應用程式。
Neon 帳戶。
Node.js (>= v18.0.0)： 從 nodejs.org 下載。
如果已啟用 IP Allow，請將 34.192.103.46 和 23.22.233.166 加入允許清單（mcp.neon.tech 個靜態 IP）。

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

選項 1：使用 API Key 快速設定

不想手動建立 API Key 嗎？

執行 neon@latest init，即可透過一個指令自動設定 Neon MCP Server：

npx neon@latest init

此方法適用於 Cursor、VS Code (GitHub Copilot) 和 Claude Code。它會透過 OAuth 驗證、為您建立 Neon API Key，並自動設定您的編輯器。

選項 2：遠端託管 MCP Server（以 OAuth 驗證）

使用 OAuth 驗證連線至 Neon 託管的 MCP Server。這是最簡單的設定方式，不需要在本機安裝此 Server，也不需要在 Client 中設定 Neon API Key。

執行以下指令，將 Neon MCP Server 加入工作區中所有偵測到的代理程式和編輯器：

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 Server 加入全域 MCP Server 清單，而非僅限專案範圍。

或者，您也可以將以下「Neon」項目加入 Client 的 MCP Server 設定檔（例如 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 Client。
瀏覽器會開啟 OAuth 視窗。依照提示授權 MCP Client 存取您的 Neon 帳戶。

使用 OAuth 驗證時，MCP Server 預設會在您個人的 Neon 帳戶下操作專案。若要存取或管理屬於組織的專案，您必須在對 MCP Client 的提示中明確提供 org_id 或 project_id。

選項 3：遠端託管 MCP Server（以 API Key 驗證）

如果您的 Client 支援，遠端 MCP Server 也支援在 Authorization 標頭中使用 API Key 進行驗證。

在 Neon Console 中建立 Neon API Key。接著，執行以下指令，將 Neon MCP Server 加入工作區中所有偵測到的代理程式和編輯器：

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」項目加入 Client 的 MCP Server 設定檔（例如 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 Key，即可將存取權限制為僅限該組織下的專案。

範圍與唯讀模式

Neon MCP 宣告 OAuth 範圍 read 和 write。您的 MCP Client 可以要求這些範圍，或者您也可以在 OAuth 權限介面中選擇。若 Client 仍傳送 *，則會將其視為寫入權限。

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

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

預設 MCP URL（可編輯授權）： 使用 https://mcp.neon.tech/mcp 連線，並在授權頁面取消勾選 允許寫入。您也可以在該頁面選擇單一專案、用於 SQL 的 Postgres 角色，以及部分工具類別。
參數化 MCP URL（固定授權）： 在 MCP Server URL 中加入 readonly、projectId、category 和／或 roleName。授權頁面會確認該授權，且不提供編輯選項。若要變更授權，請修改 URL 並重新授權。

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

查詢參數的行為如下：

API Key 流程： readonly=true 是啟用唯讀模式的方式（此流程不會交換 OAuth 範圍）。URL 變更會在下一個請求時生效。
OAuth 流程： MCP URL 上的 projectId、category、readonly 和 roleName 會構成在授權時確認的固定授權。該頁面無法將 readonly=true 擴大為寫入權限。核發權杖後，變更 URL 不會擴大該權杖的權限；請重新授權。

對於 OAuth 註冊，x-read-only 是可編輯授權頁面上「允許寫入」的初始預設值。它不會鎖定確認結果，也不會縮減包含 readonly=false 的參數化 URL 所指定的權限。API Key 請求仍會依每個請求套用 x-read-only，其優先順序低於 readonly 查詢參數。

注意： 唯讀模式會限制可用的_工具_。run_sql 仍可使用，且會在 READ ONLY 交易中執行每個查詢。run_sql_transaction 無法使用；請使用 run_sql 執行每個陳述式。這些呼叫會分別執行，且不會共用交易。若要使用交易語意，請使用允許寫入的連線。

存取控制的 URL 查詢參數

授權上下文（範圍類別、專案範圍、唯讀模式、固定的 Postgres 角色）是透過 MCP Server URL 上的 URL 查詢參數設定。API Key 請求會在每個請求中套用這些參數。OAuth 權杖則會儲存授權時確認或編輯的授權內容。

參數	說明	範例
`readonly`	啟用唯讀模式（`true`/`false`）	`?readonly=true`
`category`	限制可用的工具類別（重複指定或使用 CSV）	`?category=querying&category=schema`
`projectId`	將所有操作限制在單一專案	`?projectId=proj-123`
`roleName`	以此 Postgres 角色執行所有 SQL，而非使用擁有者角色	`?roleName=app_reader`

唯讀 + 專案範圍範例：

{
  "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"
    }
  }
}

固定 Postgres 角色範例（唯讀、單一專案、以 app_reader 執行 SQL）：

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

roleName 會為整個連線固定 Postgres 登入角色。Server 為您執行的所有 SQL（run_sql、run_sql_transaction、explain_sql_statement、get_database_tables、describe_table_schema、describe_branch、list_slow_queries、inspect_database，以及遷移和查詢調校中的 SQL）都會以該角色登入，因此 Postgres 權限會決定代理程式可以讀取或變更哪些內容。若未設定此項，SQL 會以資料庫擁有者身分執行。唯讀模式仍會在 READ ONLY 交易中包裝查詢；固定角色則額外加上由 Postgres 在登入時強制執行的限制，因此即使 SQL 脫離交易執行，也只能使用該角色的權限。

伺服器會在內部解析角色的憑證，絕不會傳回這些憑證。get_connection_string 在固定連線上無法使用。
與固定角色不同的 role_name 工具引數會遭拒。省略此引數時會使用固定角色，絕不會使用擁有者。
如果角色不存在或無法登入（例如 ALTER ROLE … NOLOGIN），呼叫會在執行任何 SQL 之前失敗。系統不會改用其他角色重試。
值必須是完全符合格式的 Postgres 角色名稱：由字母、數字、_ 或 $ 組成，且以字母或 _ 開頭，長度最多 63 個字元。其他任何值（空值、重複、加引號或含連字號）都會遭拒並回傳 400，而非忽略。
角色必須能夠登入（LOGIN），且必須存在於你查詢的每個分支上。透過 SQL 建立的角色（CREATE ROLE app_reader LOGIN PASSWORD '…'）可以使用，在 Neon Console 或 API 中建立的角色也可以。固定角色的用途在於讓角色只擁有所需權限，不多不少：對於唯讀代理程式，請在它們應該能檢視的資料表上授予 SELECT，且不要將其加入 neon_superuser。create_postgres_role 搭配 access: "read_only"，可從不含 roleName 的連線建立此類角色；它建立的角色若未使用 access，就會加入 neon_superuser。
**OAuth：**在 MCP URL 上使用 roleName 會建立固定授權。授權頁面會顯示角色，核發的權杖在重新整理後仍會保留該角色。之後變更 URL 不會改變權杖；請重新授權。使用預設 URL（可編輯同意內容）時，請改在選填的 Postgres role 欄位中輸入角色；留空則會保留資料庫擁有者。此選項推出前核發的權杖沒有固定角色，行為維持不變。
**API 金鑰：**每次請求都會從 URL 讀取角色。任何能編輯連線 URL 且持有 API 金鑰的人，都可以變更或移除角色，因此請將 URL 保存在代理程式無法控制的設定中。
固定角色僅適用於 SQL 連線。管理 API 工具仍會使用 API 金鑰或 OAuth 權杖本身的存取權；例如，compare_database_schema 是由 Neon API 計算，不受角色授權限制。搭配使用 roleName、readonly=true 和 category，也能限制這些工具。

你可以使用 /api/list-tools 端點預覽任何設定下可見的工具（不需要驗證）：

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

唯讀模式下可用的工具

主機工具：list_organizations、describe_branch、run_sql、get_database_tables、describe_table_schema、list_slow_queries、explain_sql_statement、inspect_database、get_neon_auth_config、search、fetch、search_docs、get_doc、send_feedback。

由 Management API 產生的 GET 工具（不會傳回機密），以及 query_logs（POST，唯讀）。使用 /api/list-tools?readonly=true 預覽確切的工具集合。

需要寫入權限的工具：

由 Management API 產生的寫入工具（create_project、create_branch、delete_project、…）
get_connection_string（連線字串包含具高權限角色的密碼，因此在唯讀模式下會隱藏；請改從 Neon Console 複製）
run_sql_transaction（其陳述式會在同一個工作階段中執行，因此 COMMIT 或 SET TRANSACTION READ WRITE 陳述式會結束唯讀交易）
prepare_database_migration、complete_database_migration
prepare_query_tuning、complete_query_tuning

傳輸相容性

https://mcp.neon.tech/mcp 使用無狀態 Streamable HTTP。它支援 MCP 2026-07-28 通訊協定，以及供 2025 年代用戶端使用的無狀態備援模式。已棄用的 HTTP+SSE /sse 和 /message 端點會回傳 410 Gone。

請將 Streamable HTTP 用戶端連線至 https://mcp.neon.tech/mcp。對於僅支援本機 stdio 伺服器的用戶端，請在用戶端設定中加入以下內容，讓 mcp-remote 橋接至 Streamable HTTP：

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.neon.tech/mcp"]
    }
  }
}

格式錯誤的 Origin 標頭請求會收到 403 Forbidden。任何序列化的來源都會被接受，包括網頁、瀏覽器擴充功能、桌面 WebView 和 null，因此瀏覽器型用戶端可以連線。沒有 Origin 的請求不受影響。

遠端伺服器架構

遠端伺服器以 Next.js App Router 應用程式的形式，部署在 Vercel 的 mcp.neon.tech。

[!NOTE] 根目錄的 / 路徑會重新導向至 Neon MCP Server 文件。此處沒有首頁。

核心實作區域：

app/api/[transport]/route.ts：無狀態 Streamable HTTP 端點（/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 Server 提供下列動作，並以「工具」形式公開給 MCP 用戶端。你可以使用自然語言命令，透過這些工具與 Neon 專案和資料庫互動。

工具範圍中繼資料

每個工具定義都包含一個 scope 類別，用於依授權篩選工具及提供同意操作介面。目前的類別如下：

projects
branches
endpoints
snapshots
schema
querying
neon_auth
data_api
observability
docs
functions
storage
realtime
null（沒有範圍類別的工具：search、fetch、send_feedback）

注意事項：

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 是讀取工具。
結構描述工具（?category=schema）包括主機工具 get_database_tables 和 describe_table_schema，以及產生的 compare_database_schema。
唯讀強制執行仍依賴 readOnlySafe 和伺服器端唯讀邏輯；scope 是類別中繼資料，不是獨立的讀寫切換開關。
在專案範圍模式（?projectId=...）中，沒有專案路徑的工具（list_projects、count_projects、create_project、get_project_consumption、get_branch_consumption、list_organizations、list_regions、search、fetch、…）會隱藏。delete_project 也會隱藏。

專案管理：

list_projects：列出 Neon 專案。limit 限制傳回的項目數量。
count_projects：傳回組織中的作用中專案數量。org_id 為選填，解析方式與 list_projects 相同。
describe_project：依 ID 擷取 Neon 專案（{ "project_id": "…" }）。
get_project_consumption、get_branch_consumption：依計費期間分組的每個專案或分支用量指標。接受 org_id、metrics、from、to 和 granularity，且需要 Launch、Scale、Agent、Business 或 Enterprise 方案。get_branch_consumption 也需要 project_ids，會拒絕 extra_branches_month 和 snapshot_storage_bytes_month 指標，且 Business 方案無法使用。舊版方案端點 /consumption_history/projects 不會發布。
create_project：建立 Neon 專案並等待預設運算資源就緒。不會傳回連線字串。引數為 { "name": "…", "org_id": "…", "region_id": "…" }。成功後呼叫 get_connection_string。
delete_project：刪除現有的 Neon 專案。引數為 { "project_id": "…" }。
list_organizations：列出目前使用者可存取的所有組織。可選擇使用搜尋參數，依組織名稱或 ID 篩選。

分支管理：

list_branches：列出專案中的分支。可用來將分支名稱解析為 br-… ID。
list_credentials、create_credential、revoke_credential、rotate_credential：Object Storage 和 AI Gateway 的分支範圍憑證。reveal 不是工具；輪替會直接取代現有密鑰，且不具冪等性。
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：擷取分支上的資料庫、結構描述、資料表、檢視和函式樹狀結構。
產生的分支工具會將 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

結構描述（?category=schema）：

get_database_tables、describe_table_schema
compare_database_schema：將一個資料庫的 SQL 結構描述與另一個分支進行差異比較。必須提供 database_name。省略 base_branch_id 時會與父分支比較。選填的 lsn、timestamp、base_lsn、base_timestamp 僅適用於時間點還原。

SQL 查詢執行：

get_connection_string：傳回你的資料庫連線字串。
run_sql：對指定的 Neon 資料庫執行單一 SQL 查詢。支援讀取和寫入操作。選填的 role_name 會以該 Postgres 角色登入，而非資料庫擁有者；compute_id 用於選擇運算資源；憑證會保留在伺服器上。在具有 ?roleName= 的連線上，必須省略 role_name，或使其與該值相符。
run_sql_transaction：在單一交易中，對 Neon 資料庫執行一系列 SQL 查詢。接受與 run_sql 相同的選填 role_name 和 compute_id。
get_database_tables：列出指定 Neon 資料庫中的所有資料表。
describe_table_schema：擷取特定資料表的結構描述定義，詳細列出欄位、資料類型和限制條件。

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

prepare_database_migration：啟動資料庫遷移程序。重要的是，它會建立暫存分支，以便在影響主分支之前安全地套用並測試遷移。
complete_database_migration：完成並將已準備好的資料庫遷移套用至主分支。此操作會合併暫存遷移分支中的變更，並清除暫存資源。

SQL 查詢與最佳化：

inspect_database：對分支執行 15 種預先定義的唯讀 Postgres 診斷之一 — 關聯與索引大小、索引與循序掃描使用情況、作用中的查詢與鎖定、最耗資源及最常執行的查詢、快取命中率與工作集大小、自動清理與膨脹估算，以及複寫狀態。與 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：主機工具；機密資訊已遮蔽。讀取受信任的來源、本機主機存取權、電子郵件與密碼、OAuth 提供者、電子郵件提供者、組織、魔術連結與電話號碼外掛程式，以及 webhook。
update_auth_allow_localhost、update_auth_email_and_password、update_auth_email_provider、send_auth_test_email、update_auth_plugins_organization、update_auth_plugins_magic_link、update_auth_plugins_phone_number、update_auth_webhooks：變更這些設定。update_auth_webhooks 會取代整個 webhook 設定。
list_auth_oauth_providers、add_auth_oauth_provider、update_auth_oauth_provider、delete_auth_oauth_provider
get_auth_oauth_server、update_auth_oauth_server：將 Neon Auth 設定為 OAuth 2.1 授權伺服器（包括供 MCP 伺服器使用）。與上述社交登入提供者分開。
list_auth_oauth_clients、get_auth_oauth_client、create_auth_oauth_client、update_auth_oauth_client、delete_auth_oauth_client、rotate_auth_oauth_client_secret：管理該伺服器的 OAuth 用戶端。create_auth_oauth_client 和 rotate_auth_oauth_client_secret 會傳回一次 client_secret。
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=docs 端點）：

send_feedback：向 Neon 團隊傳送匿名意見回饋。只會傳送意見回饋文字，不包含帳戶、專案或連線詳細資訊。訊息長度上限為 10,000 個字元。

可觀測性（?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）：

search_docs：使用與 neon.com 搜尋框相同的搜尋功能搜尋 neon.com（文件、API 參考、PostgreSQL 教學課程、指南、常見問題、變更記錄與部落格）。接受 query、選用的 categories（docs、api、postgresql、guides、faqs、blog、changelog），以及選用的 limit（1-40，預設為 10）。傳回依排名排列的頁面，包含 title、url、slug、category、breadcrumb、heading 和 excerpt；將 slug 傳入 get_doc 以讀取頁面。
get_doc：以 Markdown 格式擷取一個 neon.com 頁面。接受來自 search_docs 搜尋結果的 slug（例如 docs/guides/prisma 或 postgresql/tutorial/inner-join）。

函式（?category=functions）：

list_functions、get_function、update_function、delete_function、deploy_function
list_functions_custom_domains、register_functions_custom_domain、delete_functions_custom_domain
list_triggers、get_trigger、create_trigger、update_trigger、delete_trigger：排程函式觸發條件（type: "schedule"，五欄位 UTC cron）。

儲存空間（?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

即時功能（?category=realtime）：

get_realtime、enable_realtime、disable_realtime：分支即時功能狀態、啟用（選用的 allowed_origins）及停用。啟用與停用操作會等待變更套用完成。
get_realtime_secret：應用程式後端用來簽發 Realtime 權杖的共用密鑰。唯讀模式下無法使用。
rotate_realtime_secret：取代共用密鑰，並等待變更套用完成。非冪等。之後呼叫 get_realtime_secret 以取得新值。

遷移

遷移是一種隨時間管理資料庫結構描述變更的方式。透過 Neon MCP 伺服器，LLM 可以使用分開的「Start」（prepare_database_migration）和「Commit」（complete_database_migration）命令安全地執行遷移。

「Start」命令會接受遷移，並在新的暫存分支中執行。命令傳回後，會提示 LLM 在此分支上測試遷移。接著，LLM 可以執行「Commit」命令，將遷移套用至原始分支。

開發

此專案使用 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

Lint 與型別檢查

pnpm lint
pnpm typecheck

環境變數

遠端伺服器執行階段的必要變數：

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

選用：

變數	說明
`LOG_LEVEL`	Winston 記錄層級：`error`、`warn`、`info`（預設）、`debug`、`verbose`、`silly`
`NEON_MCP_DISABLE_ANALYTICS`	設為 `1` 以停用產品分析

測試金字塔

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

# 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

測試策略：

傳輸／通訊協定與使用者可見行為優先使用 E2E。
使用 integration 測試驗證確定性的工具契約與工作流程行為。
使用 unit 測試驗證純邏輯與邊界情況。
避免在合併閘門測試中依賴第三方服務的正常運作時間；在 integration/unit 測試層模擬外部相依項目。

部署

Vercel 會根據儲存庫分支設定，自動部署遠端伺服器。Pull request 可使用預覽環境。

遙測

Neon MCP 伺服器會收集產品分析資料與錯誤報告，協助我們了解使用情況並提升可靠性：

產品分析（Segment）： 使用已驗證的帳戶連線時，伺服器會傳送一個 identify 事件，其中包含您的 Neon 帳戶 ID、名稱與電子郵件地址。伺服器也會追蹤工作階段開始（server_init）、每次工具呼叫（tool_call）及非預期的伺服器錯誤（server_error）。工具呼叫事件包含工具名稱、驗證方法與用戶端，不包含工具引數或查詢結果。沒有帳戶的文件專用工具呼叫會以匿名方式追蹤。事件會傳送至 track.neon.tech，也就是 Neon 自有的分析端點。
錯誤回報（Sentry）： 非預期的伺服器錯誤會連同堆疊追蹤與請求內容一併回報。

此資料收集受 Neon 隱私權政策規範。若要在自行執行伺服器時停用分析功能，請設定 NEON_MCP_DISABLE_ANALYTICS=1。此旗標不會停用 Sentry。