Neon

官方

与 Neon 无服务器 Postgres 平台交互

GitHub

649

试用此 MCP赞助

你可以用 Neon MCP 做什么？

创建和管理项目 — 通过 create_project 或 list_projects 请求新建 Postgres 数据库、列出已有项目或删除项目。
运行 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 服务器

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 权限界面中进行选择。如果客户端仍发送 *，则将其视为写入。

只读模式限制可用的工具，禁用创建项目、分支或运行迁移等写入操作。只读工具包括列出项目、描述架构、查询数据和查看性能指标。

您可以通过两种方式设置只读模式：

默认 MCP URL（可编辑同意）： 使用 https://mcp.neon.tech/mcp 连接，并在授权页面上取消选中允许写入。您还可以在那里选择一个项目和一部分工具类别。
参数化 MCP URL（固定同意）： 在 MCP 服务器 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 不能在该页面上扩大为写入。令牌签发后，更改 URL 不会扩大该令牌；请重新授权。

对于 OAuth 注册，x-read-only 是可编辑同意上的初始“允许写入”默认值。它不会锁定确认，也不会减少包含 readonly=false 的参数化 URL。API 密钥请求仍会在每个请求中遵循 x-read-only，低于 readonly 查询参数。

注意： 只读模式限制哪些_工具_可用。此外，run_sql 工具仅保留用于只读查询。

用于访问控制的 URL 查询参数

授权上下文（范围类别、项目范围、只读模式）通过 MCP 服务器 URL 上的 URL 查询参数进行配置。API 密钥请求在每个请求中应用这些参数。OAuth 令牌存储授权时确认或编辑的授权。

参数	描述	示例
`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

远程服务器架构

远程服务器作为 Next.js App Router 应用程序在 Vercel 上运行，地址为 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 类别，用于基于授权的工具过滤和同意用户体验。当前类别包括：

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 是读取操作。
模式工具（?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 获取 Neon 项目（{ "project_id": "…" }）。
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 网关的分支范围凭据。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 查询。支持读取和写入操作。
run_sql_transaction：在单个事务中对 Neon 数据库执行一系列 SQL 查询。
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：主机工具；密钥已编辑。使用生成的 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 数据 API（?category=data_api）：

provision_neon_data_api、get_data_api、update_data_api、delete_data_api：管理分支数据库的数据 API。

搜索与发现：

search：跨组织、项目和分支搜索匹配查询的内容。返回 ID、标题和指向 Neon 控制台的直接链接。
fetch：使用 ID（通常来自搜索工具）获取特定组织、项目或分支的详细信息。

可观测性（?category=observability）：这些工具需要 Neon 平台 Beta 版，目前仅适用于 aws-us-east-2 区域中的项目。没有日志访问权限的分支会返回 HTTP 404，原因代码为 telemetry_not_enabled。

query_logs：查询分支的 OpenTelemetry 日志。在管理 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：将特定的 Neon 文档页面作为 Markdown 内容获取。首先使用 list_docs_resources 工具发现可用的页面别名，然后将别名传递给此工具。

函数（?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

迁移

迁移是一种随时间管理数据库模式更改的方式。使用 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

代码检查与类型检查

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）： 当您使用经过身份验证的账户连接时，服务器会发送一个包含您的 Neon 账户 ID、姓名和电子邮件地址的 identify 事件。它还会跟踪会话开始（server_init）、每次工具调用（tool_call）以及意外的服务器错误（server_error）。工具调用事件包含工具名称、身份验证方法和客户端，但不包含工具参数或查询结果。未使用账户的仅文档工具调用会被匿名跟踪。事件发送至 track.neon.tech，即 Neon 自身的分析端点。
错误报告（Sentry）： 意外的服务器错误会连同堆栈跟踪和请求上下文一起报告。

此收集受 Neon 隐私政策约束。要在自行运行服务器时禁用分析，请设置 NEON_MCP_DISABLE_ANALYTICS=1。该标志不会禁用 Sentry。