Neon

官方

與 Neon 無伺服器 Postgres 平台互動

GitHub

621

你可以用 Neon MCP 做什麼？

建立專案與分支 — 要求建立新的 Neon 專案或分支，例如「建立一個名為 my-database 的 Postgres 資料庫」，可透過 create_project 和 create_branch 完成。
執行 SQL 查詢與交易 — 使用 run_sql 或 run_sql_transaction 對資料庫執行單一或多重陳述式 SQL，包含非唯讀模式下的寫入操作。
檢查結構描述與資料表 — 使用 get_database_tables 列出資料表，或透過 describe_table_schema 取得資料表的完整欄位／約束定義。
安全地規劃與套用遷移 — 使用 prepare_database_migration 啟動遷移，在暫存分支上測試，再以 complete_database_migration 完成。
調整緩慢查詢 — 使用 list_slow_queries 找出瓶頸，或透過 explain_sql_statement 取得執行計畫，再以 prepare_query_tuning 測試修正。
探索專案與日誌 — 使用 search 跨組織、專案與分支搜尋，或使用 query_logs 和 list_log_fields 篩選結構化日誌。

文件

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、代理技能和 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。這是最簡單的設定方式，無需在本機安裝此伺服器，也不需要用戶端設定 Neon API 金鑰。

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

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

新增 -g 旗標，將 Neon MCP Server 新增至全域 MCP server 清單，而非專案範圍。

或者，您可以將下列 "Neon" 項目新增至用戶端的 MCP server 設定檔（例如 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 client。
瀏覽器將開啟 OAuth 視窗。依照提示授權您的 MCP client 存取您的 Neon 帳戶。

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

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

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

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

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

或者，您可以將下列 "Neon" 項目新增至用戶端的 MCP server 設定檔（例如 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 client 可以直接請求這些範圍，或者您可以在 OAuth 權限 UI 中進行選擇。

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

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

OAuth 範圍選擇（建議）： 在 OAuth 中，取消勾選授權 UI 中的完整存取即可選取唯讀。
readonly 查詢參數： 將 ?readonly=true 新增至您的 MCP server 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 作為後備（優先順序低於查詢參數）。

注意： 唯讀模式限制可用的_tools_。此外，run_sql 工具僅適用於唯讀查詢。

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

授權上下文（範圍類別、專案範圍、唯讀模式）透過 MCP server URL 上的 URL 查詢參數設定。設定會隨每個請求傳輸並立即生效 — 無需重新驗證。

Param	Description	Example
`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
get_neon_auth_config
query_logs, list_log_fields, list_log_field_values
search, fetch, list_docs_resources, get_doc_resource

需要寫入存取權限的工具：

create_project, delete_project
create_branch, delete_branch, reset_from_parent
provision_neon_auth, configure_neon_auth, provision_neon_data_api
prepare_database_migration, complete_database_migration
prepare_query_tuning, complete_query_tuning

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

MCP 支援兩種遠端伺服器傳輸：已棄用的 Server-Sent Events (SSE) 和較新且建議使用的 Streamable HTTP。如果您的 LLM 用戶端尚不支援 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

遠端伺服器架構

遠端伺服器以 Next.js App Router 應用程式的形式在 Vercel 上執行，位於 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 Server 提供下列動作，這些動作以「工具」的形式公開給 MCP Clients。您可以使用這些工具，以自然語言指令與您的 Neon 專案和資料庫互動。

工具範圍中繼資料

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

projects
branches
schema
querying
neon_auth
data_api
observability
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。它允許開發人員透過與 Auth 提供者建立整合，輕鬆設定驗證基礎架構。
configure_neon_auth：設定分支的現有 Neon Auth 整合 — 管理信任的來源、localhost 存取、驗證方法、OAuth 提供者和交易電子郵件提供者。
get_neon_auth_config：讀取分支的完整 Neon Auth 設定，包括整合中繼資料和可設定的設定（秘密已遮蔽）。

Neon Data API：

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

搜尋與探索：

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

可觀測性：

query_logs：使用結構化篩選條件（來源、服務名稱、嚴重性、時間範圍）查詢 Neon 無伺服器函式和其他服務發出的日誌。日誌是基於 OpenTelemetry。
list_log_fields：列出可在分支上篩選的日誌欄位（標籤），例如 service_name、severity_text 和 scope_name。請在 query_logs 之前使用。
list_log_field_values：列出分支和時間範圍內日誌欄位的相異值，以探索要傳遞給 query_logs 的具體值。

文件和資源：

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

遷移

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

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

開發

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

專案結構

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

corepack enable
pnpm install

本機開發

# 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 用戶端密鑰
`COOKIE_SECRET`	用於簽署 Cookie 的密鑰
`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

測試策略：

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

部署

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