Neon

官方

与 Neon 无服务器 Postgres 平台交互

GitHub

623

你可以用 Neon MCP 做什么？

创建和管理项目 — 通过 create_project、list_projects 和 delete_project 创建、列出或删除 Neon 项目。
运行 SQL 查询 — 使用 run_sql 或 run_sql_transaction 执行读写 SQL，并使用 get_database_tables 列出表。
管理分支 — 使用 create_branch 创建分支，通过 compare_database_schema 比较架构差异，或使用 reset_from_parent 从父分支重置。
执行安全迁移 — 使用 prepare_database_migration 在临时分支上测试，然后使用 complete_database_migration 应用迁移。
优化查询性能 — 使用 list_slow_queries 查找慢查询，通过 explain_sql_statement 获取执行计划，并使用 prepare_query_tuning 测试调优。

文档

Neon MCP Server

Neon MCP Server 是一款开源工具，让你能够以自然语言与 Neon 上的 Lakebase Postgres 数据库进行交互。

Model Context Protocol (MCP) 是一种标准化协议，旨在管理大型语言模型（LLM）与外部系统之间的上下文。本仓库为 Neon 提供了一个远程 MCP Server。

Neon 的 MCP server 充当自然语言请求与 Neon API 之间的桥梁。它基于 MCP 构建，将你的请求转换为所需的 API 调用，使你能够无缝地完成创建项目和分支、运行查询以及执行数据库迁移等任务。

Neon MCP server 的一些主要功能包括：

自然语言交互： 使用直观的对话式命令管理 Neon 数据库。
简化的数据库管理： 无需编写 SQL 或直接使用 Neon API 即可执行复杂操作。
对非开发者友好： 让具有不同技术背景的用户都能与 Neon 数据库交互。
数据库迁移支持： 利用 Neon 的分支功能，通过自然语言发起数据库 schema 变更。

例如，在 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 不可用的情况下将远程 agent 连接到 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 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。

运行以下命令，为工作区中检测到的所有 agent 和编辑器添加 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 Key 的身份验证）

如果你的客户端支持，远程 MCP Server 还支持在 Authorization 请求头中使用 API key 进行身份验证。

在 Neon Console 中创建 Neon API key。然后运行以下命令，为工作区中检测到的所有 agent 和编辑器添加 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 key 可将访问权限限制为该组织下的项目。

作用域与只读模式

Neon MCP 支持 OAuth 作用域 read、write 和 *（* 表示两者）。你的 MCP client 可以直接请求这些作用域，也可以在 OAuth 权限界面中进行选择。

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

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

OAuth 作用域选择（推荐）： 在 OAuth 中，取消选中授权界面中的 Full access 即可选择只读。
readonly 查询参数： 在你的 MCP server URL 中添加 ?readonly=true：

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

查询参数的行为：

API key 流程： readonly=true 是启用只读模式的方式（此流程中没有 OAuth 作用域交换）。
OAuth 流程： readonly=true 会覆盖 OAuth 作用域。如果没有该参数，则只读模式由 OAuth 同意界面中选择的作用域决定。

旧版 HTTP 请求头 x-read-only 也作为回退方式受支持（优先级低于查询参数）。

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

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

授权上下文（作用域类别、项目范围、只读模式）通过 MCP server URL 上的查询参数进行配置。配置会随每个请求一起传递并立即生效——无需重新认证。

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

类别过滤示例（仅查询和 schema 工具）：

{
  "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, inspect_database
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 传输：已弃用的 Server-Sent Events (SSE) 和更新的、推荐的 Streamable HTTP。如果你的 LLM 客户端尚不支持 Streamable HTTP，你可以将端点从 https://mcp.neon.tech/mcp 切换为 https://mcp.neon.tech/sse 以改用 SSE。

运行以下命令，使用 SSE 传输为工作区中检测到的所有 agent 和编辑器添加 Neon MCP Server：

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

远程 Server 架构

远程 server 作为 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 客户端。你可以使用这些工具通过自然语言命令与你的 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 查询与优化：

inspect_database：对分支运行 14 种预定义的只读 Postgres 诊断之一——关系与索引大小、索引与顺序扫描使用情况、活动查询与锁、最重与最频繁查询、缓存命中率与工作集大小、autovacuum 与膨胀估算，以及复制状态。与 neon inspect db CLI 命令执行相同的检查。其中四项需要 pg_stat_statements 或 neon 扩展。
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：为基于 HTTP 的数据库访问配置 Neon Data API，可选择通过 Neon Auth 或外部 JWKS 提供商进行 JWT 认证。

搜索与发现：

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

可观测性： 这些工具需要 Neon Platform Beta，目前仅适用于位于 aws-us-east-2 区域的项目。没有日志访问权限的分支会返回 HTTP 404，原因是 telemetry_not_enabled。

query_logs：查询 Neon 无服务器函数和其他服务发出的 OpenTelemetry 日志。使用结构化过滤器按来源、服务名称、严重级别和时间窗口进行过滤，或使用原始 logql 来表示结构化输入无法表达的流选择器和行过滤器。
list_log_fields：列出可以在分支上枚举值的日志字段，例如 service_name、severity_text 和 scope_name。请在 list_log_field_values 之前使用。
list_log_field_values：列出分支和时间窗口内日志字段的不同值，以发现用于结构化过滤器或原始 logql 的具体值。

文档与资源：

list_docs_resources：通过从 https://neon.com/docs/llms.txt 获取索引来列出所有可用的 Neon 文档页面。返回页面 URL 和标题，可以使用 get_doc_resource 工具单独获取。
get_doc_resource：以 markdown 内容获取特定的 Neon 文档页面。请先使用 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

代码检查与类型检查

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 会根据仓库分支配置自动部署远程服务器。预览环境可用于拉取请求。