Neon MCP 服务器

Neon MCP 服务器 是一款开源工具，可让您以 自然语言 与您的 Neon Postgres 数据库进行交互。

模型上下文协议（MCP）是一种 标准化协议，旨在管理大型语言模型（LLM）与外部系统之间的上下文。此仓库提供了一个用于 Neon 的远程 MCP 服务器。

Neon 的 MCP 服务器充当自然语言请求与 Neon API 之间的桥梁。它基于 MCP 构建，可将您的请求转换为必要的 API 调用，从而让您无缝地管理创建项目和分支、运行查询以及执行数据库迁移等任务。

Neon MCP 服务器的一些主要功能包括：

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

例如，在 Claude Code 或任何 MCP 客户端中，您可以使用自然语言完成以下操作：

• 让我们创建一个新的 Postgres 数据库，命名为 "my-database"。然后创建一个名为 users 的表，包含以下列：id、name、email 和 password。
• 我想在我的名为 "my-project" 的项目上运行一次迁移，修改 users 表以添加一个名为 "created_at" 的新列。
• 你能给我总结一下我所有的 Neon 项目以及每个项目中的数据吗？

[!警告]
Neon MCP 服务器安全注意事项
Neon MCP 服务器通过自然语言请求赋予了强大的数据库管理能力。在执行 LLM 请求的操作之前，请务必先审查并授权。 确保只有授权用户和应用程序才能访问 Neon MCP 服务器。

Neon MCP 服务器仅适用于本地开发和 IDE 集成。我们不建议在生产环境中使用 Neon MCP 服务器。 它可以执行可能导致意外或未经授权更改的强大操作。

更多信息请参阅 MCP 安全指南 →。

设置 Neon MCP 服务器

设置 Neon MCP 服务器有几种方法：

1. 使用 API 密钥快速设置（Cursor、VS Code 和 Claude Code）： 运行 neonctl@latest init，即可通过一条命令自动配置 Neon 的 MCP 服务器、agent skills 和 VS Code 扩展。
2. 远程 MCP 服务器（基于 OAuth 的身份验证）： 使用 OAuth 进行身份验证，连接到 Neon 的托管 MCP 服务器。这种方法更为便捷，无需管理 API 密钥。此外，您还将自动获得最新功能和改进。
3. 远程 MCP 服务器（基于 API 密钥的身份验证）： 使用 API 密钥进行身份验证，连接到 Neon 的托管 MCP 服务器。如果您希望将远程代理连接到无法使用 OAuth 的 Neon，则此方法非常有用。同时，您也将自动获得最新功能和改进。

先决条件

• 一个 MCP 客户端应用。
• 一个 Neon 账户。
• Node.js（>= v18.0.0）： 从 nodejs.org 下载。

对于开发，您还需要安装 Bun。

方法 1. 使用 API 密钥快速设置

不想手动创建 API 密钥吗？

运行 neonctl@latest init，即可通过一条命令自动配置 Neon 的 MCP 服务器：

npx neonctl@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

或者，您也可以将以下“Neon”条目添加到您的客户端 MCP 服务器配置文件中（例如 mcp.json、mcp_config.json）：

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/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 --header "Authorization: Bearer <$NEON_API_KEY>"

或者，您也可以将以下“Neon”条目添加到您的客户端 MCP 服务器配置文件中（例如 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 客户端可以直接请求这些作用域，或者您也可以在 OAuth 权限 UI 中进行选择。

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

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

1. OAuth 作用域选择（推荐）： 在 OAuth 授权界面中，取消勾选 完全访问权限 即可选择只读模式。
2. X-Neon-Read-Only 头部： 将 X-Neon-Read-Only: true 添加到您的 MCP 服务器配置中：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "X-Neon-Read-Only": "true"
      }
    }
  }
}

该头部的行为如下：

• API 密钥流程： X-Neon-Read-Only 是启用只读模式的方式（此流程中没有 OAuth 作用域交换）。
• OAuth 流程： X-Neon-Read-Only: true 的行为类似于默认同意设置中的 scope=read（完全访问权限默认未选中），但用户仍可在批准前在 OAuth UI 中覆盖此设置。

旧版头部 x-read-only 也受支持。

[!重要提示] 如果您更改 MCP 配置文件（例如切换只读模式或改为项目范围的设置），这些更改仅对 OAuth 流程 生效，且需要先注销并重新登录。 OAuth 权限/作用域是在创建新的 OAuth 令牌时与会话绑定的。 这不适用于 API 密钥流程。

注意： 只读模式限制的是可用的 工具，而非 SQL 内容。run_sql 工具仍然可用，并可执行任何 SQL，包括 INSERT/UPDATE/DELETE。如需真正的只读 SQL 访问权限，请使用具有受限权限的数据库角色。

只读模式下可用的工具

• 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
• search、fetch、list_docs_resources、get_doc_resource

需要写入权限的工具：

• create_project、delete_project
• create_branch、delete_branch、reset_from_parent
• provision_neon_auth、provision_neon_data_api
• prepare_database_migration、complete_database_migration
• prepare_query_tuning、complete_query_tuning

服务器发送事件 (SSE) 传输（已弃用）

MCP 支持两种远程服务器传输方式：已弃用的服务器发送事件 (SSE) 和更新、推荐的流式 HTTP。如果您的 LLM 客户端尚不支持流式 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 运行。

[!注释] 根路径 / 会重定向到 Neon MCP 服务器文档。不存在着陆页。

核心实现区域：

• landing/app/api/[transport]/route.ts: MCP 传输端点，用于流式 HTTP (/mcp) 和 SSE (/sse)
• landing/app/api/authorize/、landing/app/callback/、landing/app/api/token/、landing/app/api/revoke/: OAuth 流程端点
• landing/app/.well-known/: OAuth 发现元数据端点
• landing/mcp-src/: MCP 服务器、工具、处理器、分析以及 Sentry 集成
• landing/lib/: 兼容 Next.js 的辅助工具（OAuth、配置、错误处理）
• landing/mcp-src/utils/read-only.ts: 只读模式和作用域处理

指南

• Neon MCP 服务器指南
• 将 MCP 客户端连接到 Neon
• Cursor 与 Neon MCP 服务器
• Claude Desktop 与 Neon MCP 服务器
• Cline 与 Neon MCP 服务器
• Windsurf 与 Neon MCP 服务器
• Zed 与 Neon MCP 服务器

功能

支持的工具

Neon MCP 服务器提供以下操作，这些操作作为“工具”暴露给 MCP 客户端。您可以使用这些工具通过自然语言命令与您的 Neon 项目和数据库进行交互。

工具范围元数据

每个工具定义都包含一个 scope 类别，用于基于授权的工具筛选和同意用户界面。当前类别包括：

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• docs
• null（无范围类别的工具）

注意事项：

• compare_database_schema 归类于 schema。
• provision_neon_data_api 归类于 data_api（与 neon_auth 分开）。
• 只读强制仍然依赖于 readOnlySafe 和服务器端的只读逻辑；scope 是类别元数据，而不是独立的读写开关。
• 在项目范围模式下（X-Neon-Project-Id），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 认证：

• provision_neon_auth：为 Neon 项目配置 Neon 认证。它允许开发者通过与认证提供商集成，轻松设置身份验证基础设施。

Neon 数据 API：

• provision_neon_data_api：为基于 HTTP 的数据库访问配置 Neon 数据 API，支持通过 Neon 认证或外部 JWKS 提供商进行可选的 JWT 身份验证。

搜索与发现：

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

文档与资源：

• 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 服务器，大型语言模型可以使用单独的“开始”（prepare_database_migration）和“提交”（complete_database_migration）命令安全地执行迁移。

“开始”命令接受迁移脚本并在一个新的临时分支上运行。完成后，该命令会提示大型语言模型在此分支上测试迁移。随后，大型语言模型可以运行“提交”命令，将迁移应用到原始分支上。

开发

该项目使用 Bun 作为包管理器和运行时。

项目结构

MCP 服务器代码位于 landing/ 目录中，这是一个部署在 Vercel 上的 Next.js 应用程序，地址为 mcp.neon.tech。

cd landing
bun install

本地开发

# 启动 Next.js 开发服务器（用于远程 MCP 服务器）
bun run dev

代码检查与类型检查

bun run lint
bun run 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

测试金字塔

所有测试均从 landing/ 目录运行。

cd landing

# 单元测试
bun run test:unit

# 集成测试
bun run test:integration

# MCP 协议端到端测试（真实的 MCP 客户端/服务器工具调用）
bun run test:e2e:mcp

# 网站端到端测试（使用 Playwright；会先 provision/验证临时数据库）
bun run test:e2e:web

# 完整的端到端测试套件
bun run test:e2e

# 完整测试金字塔（单元 + 集成 + e2e；用于 CI）
bun run test

测试策略：

• 对于传输/协议及用户可见的行为，优先使用 E2E 测试。
• 使用 集成 测试来验证确定性的工具契约和工作流行为。
• 使用 单元 测试来覆盖纯逻辑和边缘情况。
• 避免在合并准入测试中依赖第三方服务的可用性；在集成/单元层模拟外部依赖。

部署

Vercel 会根据仓库分支配置自动部署远程服务器。针对拉取请求，还提供预览环境。

Neon MCP Server 快速上手指南

Neon MCP Server 是一个开源工具，允许你通过自然语言与 Neon Postgres 数据库进行交互。它基于模型上下文协议（MCP），将你的指令转化为 API 调用，从而轻松管理项目、分支、执行查询和数据库迁移。

⚠️ 安全警告

• Neon MCP Server 拥有强大的数据库管理能力。在执行 LLM 请求的操作前，务必审查并授权。
• 该工具仅适用于本地开发和 IDE 集成，不建议在生产环境中使用。

1. 环境准备

在开始之前，请确保满足以下前置条件：

• Neon 账户：拥有一个 Neon 账户。
• Node.js：版本需 >= v18.0.0（从 nodejs.org 下载）。
• MCP 客户端：已安装支持 MCP 的编辑器或 Agent，例如：
  • Cursor
  • VS Code (配合 GitHub Copilot)
  • Claude Code
  • Cline, Windsurf, Zed 等
• (可选) Bun：如果你计划参与开发，需要安装 Bun。

2. 安装步骤

你可以选择以下三种方式之一进行配置。推荐初学者使用方案一或方案二。

方案一：一键快速设置（推荐）

此方法会自动处理 OAuth 认证、创建 API Key 并配置编辑器。适用于 Cursor、VS Code 和 Claude Code。

在终端运行以下命令：

npx neonctl@latest init

方案二：远程托管服务 + OAuth 认证（无需 API Key）

此方法最便捷，无需手动管理 API Key，且能自动获取最新功能。

方法 A：使用命令行自动添加 运行以下命令，为工作区中检测到的所有 Agent 和编辑器添加配置：

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

方法 B：手动修改配置文件 在你的 MCP 客户端配置文件（如 mcp.json 或 mcp_config.json）中添加以下内容：

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

配置完成后，重启或刷新你的 MCP 客户端。浏览器将弹出 OAuth 窗口，请按提示授权访问你的 Neon 账户。

方案三：远程托管服务 + API Key 认证

适用于无法使用 OAuth 的远程 Agent 场景。

1. 在 Neon Console 创建 API Key。
2. 运行以下命令（将 <$NEON_API_KEY> 替换为你的实际密钥）：

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

或者手动配置 mcp.json：

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

3. 基本使用

配置完成后，你可以在支持的 MCP 客户端（如 Cursor 聊天窗口或 Claude Code）中直接使用自然语言操作数据库。

常用示例

创建数据库和表：

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?

进阶：只读模式

为了防止误操作，你可以启用只读模式（禁用创建项目、分支或迁移等写入操作，但保留 SQL 查询功能）。

配置方法： 在 mcp.json 中添加 X-Neon-Read-Only 头：

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "X-Neon-Read-Only": "true"
      }
    }
  }
}

注意：只读模式仅限制可用的工具（如禁止调用 create_project），run_sql 工具仍然可用并可执行任意 SQL（包括 INSERT/UPDATE/DELETE）。若需严格的 SQL 只读权限，请在数据库层面配置角色权限。