Neon

官方

与 Neon 无服务器 Postgres 平台交互

你可以用 Neon MCP 做什么？

创建项目和分支 — 请助手创建新的 Postgres 项目，或创建用于架构变更的分支，例如 feature-x。
运行 SQL 查询 — 对 Neon 数据库执行单条查询或多语句事务，并获取返回的行。
检查架构 — 列出数据库中的表，并查看表的列、数据类型和约束。
安全迁移 — 在临时分支上准备迁移，然后完成迁移，将变更应用到主分支。
优化慢查询 — 查找慢查询、查看执行计划，并在临时分支上测试建议的优化方案。
汇总项目 — 列出 Neon 项目并描述各分支，以查看每个项目包含哪些数据库和表。

托管 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。如果你想将远程代理连接到 Neon，而 OAuth 不可用，此方法会很有用。此外，新功能和改进发布后，你会自动获得。

前提条件

一个 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，也无需在客户端配置 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" 条目添加到客户端的 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 的身份验证）

如果客户端支持，远程 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" 条目添加到客户端的 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 权限界面中选择。若客户端仍发送 *，则会将其视为写入权限。

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

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

默认 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 key：**每次请求都会从 URL 读取角色。因此，任何能够编辑连接 URL 且持有 API key 的人都可以更改或移除该角色，所以请将 URL 保存在代理无法控制的配置中。
固定角色仅适用于 SQL 连接。管理 API 工具仍使用 API key 或 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、list_incidents。

生成的管理 API 工具中，GET 请求且不返回机密信息的工具，以及 query_logs（POST，只读）。使用 /api/list-tools?readonly=true 预览确切的工具集合。

需要写入权限的工具：

生成的管理 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）

说明：

管理 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：用于对象存储和 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，或使其与之匹配。返回行数组，最多包含 max_rows 行（默认 100 行，最多 10,000 行）；如果行数被截断，第二个内容块会包含 { totalRowCount, truncated, note }。查询失败时会返回 Postgres SQLSTATE、错误位置以及任何详细信息、提示或上下文。
run_sql_transaction：在单个事务中针对 Neon 数据库执行一系列 SQL 查询。接受与 run_sql 相同的可选参数 role_name、compute_id 和 max_rows。max_rows 对每条语句分别生效；如果有任何语句的结果被截断，第二个内容块会包含每条语句的摘要。
get_database_tables：列出指定 Neon 数据库中的所有表。
describe_table_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：机密信息已隐藏。读取受信任的来源、本地主机访问、电子邮件和密码、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_logs_export：更改这些设置。update_auth_webhooks 会替换整个 webhook 配置。update_auth_logs_export 用于启用或停用将 Neon Auth 事件导出到 Neon Platform 日志；未启用日志导出的项目只接受 enabled: false。
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；此服务器将其视为只读操作。
query_loki_logs：在分支兼容 Loki 的只读 API 上运行 LogQL 范围查询，并返回 Loki 的响应：按流标签分组的日志行及纳秒级时间戳。
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

代码检查与类型检查

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 测试。
对确定性的工具契约和工作流行为，使用集成测试。
对纯逻辑和边缘情况，使用单元测试。
避免在合并门禁测试中依赖第三方服务的正常运行时间；在集成/单元测试层模拟外部依赖。

部署

Vercel 会根据仓库分支配置自动部署远程服务器。拉取请求可使用预览环境。

遥测

Neon MCP 服务器会收集产品分析数据和错误报告，以帮助我们了解使用情况并提高可靠性：

产品分析（Segment）： 使用已认证账户连接时，服务器会发送一个 identify 事件，其中包含你的 Neon 账户 ID、姓名和电子邮件地址。服务器还会跟踪会话开始（server_init）、每次工具调用（tool_call）以及意外的服务器错误（server_error）。工具调用事件包含工具名称、身份验证方式和客户端，不包含工具参数或查询结果。没有账户的纯文档工具调用会以匿名方式跟踪。授权后显示的页面会报告页面已显示（auth_complete_viewed，包含结果和客户端），以及页面上的哪些按钮和链接被使用（auth_complete_action）；浏览器只会发送随机页面浏览 ID，绝不会发送授权码或你的身份信息。事件会发送到 track.neon.tech，即 Neon 自有的分析端点。
错误报告、跟踪和日志（Sentry）： 意外的服务器错误会连同堆栈跟踪以及请求的方法和路径一起上报。不会发送请求标头、正文、Cookie 或查询字符串。每个请求和工具调用都会被跟踪，记录工具名称、客户端名称、账户 ID、调用是否失败，以及服务器分配给 2025 年前后客户端的会话 ID 和客户端在 _meta.threadId 中发送的对话 ID。跟踪数据不包含工具参数或结果。服务器日志也会发送到 Sentry。此集合受 Neon 隐私政策约束。自行运行服务器时，如需停用分析功能，请设置 NEON_MCP_DISABLE_ANALYTICS=1。该标志不会停用 Sentry。