Neon

官方

與 Neon 無伺服器 Postgres 平台互動

你可以用 Neon MCP 做什麼？

建立與管理專案 — 要求建立新的 Postgres 資料庫、列出既有專案，或透過 create_project 或 list_projects 刪除專案。
執行 SQL 查詢與交易 — 使用 run_sql 或 run_sql_transaction 對資料庫執行單一或多重陳述式 SQL，包括寫入操作。
檢查與最佳化效能 — 透過 list_slow_queries、explain_sql_statement 或 inspect_database 找出慢查詢、取得執行計畫，或執行如快取命中率等診斷。
安全地遷移結構 — 在暫時分支上開始遷移、測試，然後透過 prepare_database_migration 和 complete_database_migration 將其提交至主分支。
探索資料庫結構 — 使用 get_database_tables、describe_table_schema 或 compare_database_schema 列出資料表、描述欄位結構，或比較跨分支的結構差異。

託管 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 金鑰快速設定（Cursor、VS Code 和 Claude Code）： 執行 neon@latest init 以單一指令自動設定 Neon 的 MCP Server、agent skills 和 VS Code 擴充功能。
遠端 MCP Server（基於 OAuth 的驗證）： 使用 OAuth 連線到 Neon 受管理的 MCP server 進行驗證。此方法更方便，因為無需管理 API 金鑰。此外，您會在功能發佈時自動收到最新的功能和改進。
遠端 MCP Server（基於 API 金鑰的驗證）： 使用 API 金鑰連線到 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+（pnpm 透過 Corepack 提供 — 執行 corepack enable 以啟用它）。

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

不想手動建立 API 金鑰？

執行 neon@latest init 以單一指令自動設定 Neon 的 MCP Server：

npx neon@latest init

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

選項 2. 遠端託管 MCP Server（基於 OAuth 的驗證）

使用 OAuth 連線到 Neon 受管理的 MCP server 進行驗證。這是最簡單的設定，無需在本機安裝此 server，也無需在 client 中設定 Neon API 金鑰。

執行以下指令，為您工作區中所有偵測到的代理程式和編輯器新增 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 金鑰的驗證）

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

在 Neon Console 中建立 Neon API 金鑰。接著，執行以下指令，為您工作區中所有偵測到的代理程式和編輯器新增 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 金鑰，以將存取權限制在該組織下的專案。

範圍與唯讀模式

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

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

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

預設 MCP URL（可編輯同意）： 使用 https://mcp.neon.tech/mcp 連線，並在授權頁面上取消勾選 允許寫入。您也可以在那裡選擇一個專案和一部分工具類別。
參數化 MCP URL（固定同意）： 在 MCP server URL 上放置 readonly、projectId 和/或 category。授權頁面會確認該授權，且不提供編輯器。變更 URL 並重新授權以變更授權。

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

查詢參數的行為方式：

API 金鑰流程： readonly=true 是啟用唯讀模式的方式（此流程中沒有 OAuth 範圍交換）。URL 變更將在下一個請求時套用。
OAuth 流程： MCP URL 上的 projectId、category 和 readonly 是在授權時確認的固定授權。readonly=true 無法在該頁面上擴大為寫入。發出 token 後，變更 URL 不會擴大該 token；請重新授權。

對於 OAuth 註冊，x-read-only 是可編輯同意上的初始允許寫入預設值。它不會鎖定確認，也不會減少包含 readonly=false 的參數化 URL。API 金鑰請求仍會依每個請求遵循 x-read-only，低於 readonly 查詢參數。

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

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

授權上下文（範圍類別、專案範圍、唯讀模式）透過 MCP server URL 上的 URL 查詢參數設定。API 金鑰請求會在每個請求時套用這些參數。OAuth token 會儲存在授權時確認或編輯的授權。

參數	說明	範例
`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 Console 複製）
prepare_database_migration、complete_database_migration
prepare_query_tuning、complete_query_tuning

Server-Sent Events (SSE) 傳輸（已棄用）

MCP 支援兩種遠端 server 傳輸：已棄用的 Server-Sent Events (SSE) 和較新、建議使用的 Streamable HTTP。如果您的 LLM client 尚不支援 Streamable HTTP，您可以將端點從 https://mcp.neon.tech/mcp 切換為 https://mcp.neon.tech/sse 以改用 SSE。

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

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

遠端 Server 架構

遠端 server 在 Vercel 上以 Next.js App Router 應用程式執行，位於 mcp.neon.tech。

[!NOTE] 根目錄 / 路徑會重新導向至 Neon MCP Server 文件。沒有登陸頁面。

核心實作區域：

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 server、工具、處理器、分析和 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（沒有範圍類別的工具）

備註：

管理 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。
list_credentials、create_credential、revoke_credential、rotate_credential：物件儲存和 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：取得分支上的資料庫、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 主控台的直接連結。
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
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

遷移

遷移是一種隨著時間管理資料庫 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`
`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） 測試來驗證傳輸/協定與使用者可見行為。
使用整合測試來驗證確定性的工具契約與工作流程行為。
使用單元測試來驗證純邏輯與邊界情況。
避免在合併閘道測試中依賴第三方服務的可用性；在整合/單元測試層級模擬外部依賴。

部署

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

遙測

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

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

此收集行為受 Neon 隱私權政策規範。若您自行執行伺服器並想停用分析，請設定 NEON_MCP_DISABLE_ANALYTICS=1。該旗標不會停用 Sentry。