Neon MCP 服务器

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

模型上下文协议（MCP）是一个全新的标准化协议，用于管理大型语言模型（LLM）与外部系统之间的上下文。本仓库提供了 Neon 的安装程序与 MCP 服务器实现。

Neon MCP 服务器在自然语言请求与 Neon API 之间架起桥梁。基于 MCP 协议构建，它能将您的请求转换为必要的 API 调用，使您能够无缝管理创建项目与分支、执行查询以及数据库迁移等任务。

Neon MCP 服务器的核心功能包括：

• 自然语言交互：通过直观的对话式命令管理 Neon 数据库
• 简化数据库管理：无需编写 SQL 或直接调用 Neon API 即可执行复杂操作
• 提升工作效率：优化数据库管理与开发工作流
• 非技术人员友好：使不同技术背景的用户都能轻松操作 Neon 数据库
• 数据库迁移支持：通过自然语言触发，利用 Neon 分支功能实现数据库模式变更

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

• 新建一个名为"my-database"的 Postgres 数据库，然后创建包含id、name、email和password字段的users表
• 对"my-project"项目中的users表执行迁移，新增created_at字段
• 请汇总我所有的 Neon 项目及其数据内容

[!注意]
Neon MCP 服务器通过自然语言请求授予强大的数据库管理能力。请务必在 LLM 请求执行前审查并确认操作。确保仅授权用户和应用程序可访问 Neon MCP 服务器及 Neon API 密钥。

配置 Neon MCP 服务器

您有两种连接 MCP 客户端的方式：

1. 远程 MCP 服务器（预览版）：通过 OAuth 认证连接 Neon 托管的 MCP 服务器。此方式更便捷，无需管理 API 密钥，且能自动获取最新功能更新。

2. 本地 MCP 服务器：在本地运行 Neon MCP 服务器，使用 Neon API 密钥认证。

前置条件

• MCP 客户端应用
• Neon 账户
• Node.js (>= v18.0.0) 和 npm：从 nodejs.org 下载

若选择本地 MCP 服务器，还需准备 Neon API 密钥。参见 Neon API 密钥文档 生成指南。

选项 1. 远程托管 MCP 服务器（预览版）

通过 OAuth 认证连接 Neon 托管的 MCP 服务器。这是最简单的配置方案，无需本地安装服务器，也无需在客户端配置 API 密钥。

• 在客户端的 MCP 服务器配置文件（如 mcp.json、mcp_config.json）添加以下"Neon"条目：

  json 复制代码

  {
    "mcpServers": {
      "Neon": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://mcp.neon.tech/sse"
        ]
      }
    }
  }

• 保存配置文件

• 重启或刷新 MCP 客户端

• 浏览器将弹出 OAuth 窗口，按提示授权客户端访问 Neon 账户

选项 2. 本地 MCP 服务器

在本地运行 Neon MCP 服务器。

通过 Smithery 安装：

npx -y @smithery/cli@latest install neon --client <客户端名称>

按提示输入从前置条件章节获取的 Neon API 密钥。
将 <客户端名称> 替换为您的 MCP 客户端应用名称。支持以下客户端：

• claude 适用于 Claude Desktop
• cursor 适用于 Cursor（通过 smithery 安装将使 MCP 服务器成为 Cursor 的全局服务器）
• windsurf 适用于 Windsurf Editor
• roo-cline 适用于 Roo Cline VS Code 扩展
• witsy 适用于 Witsy
• enconvo 适用于 Enconvo
• vscode 适用于 Visual Studio Code (预览版)

安装完成后重启 MCP 客户端。

通过 npm 安装

如果您的客户端未列出，可手动将 Neon MCP 服务器配置添加到客户端的 mcp_config 文件。

在客户端的 mcp_config 文件的 mcpServers 部分添加以下 JSON 配置，将 <您的_NEON_API_密钥> 替换为实际密钥：

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon", "start", "<您的_NEON_API_密钥>"]
    }
  }
}

故障排除

如果客户端不使用 JSON 配置 MCP 服务器（如旧版 Cursor），可在提示时使用以下命令：

npx -y @neondatabase/mcp-server-neon start <您的_NEON_API_密钥>

Windows 系统故障排除

Windows 用户若遇到问题，可能需要使用命令提示符（cmd）或 Windows Subsystem for Linux（wsl）运行命令。配置示例如下：

{
  "mcpServers": {
    "neon": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@neondatabase/mcp-server-neon", "start", "<您的_NEON_API_密钥>"]
    }
  }
}

{
  "mcpServers": {
    "neon": {
      "command": "wsl",
      "args": ["npx", "-y", "@neondatabase/mcp-server-neon", "start", "<您的_NEON_API_密钥>"]
    }
  }
}

使用指南

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

功能特性

支持的工具

Neon MCP 服务器提供以下"工具"供 MCP 客户端调用，通过自然语言命令管理 Neon 项目与数据库。

项目管理：

• list_projects：获取 Neon 项目列表，汇总账户下所有项目信息
• describe_project：查询特定 Neon 项目的详细信息，包括 ID、名称及相关分支和数据库
• create_project：在账户中创建新 Neon 项目。项目是分支、数据库、角色和计算资源的容器
• delete_project：删除现有 Neon 项目及其所有关联资源

分支管理：

• create_branch：在指定项目中创建新分支。利用 Neon 分支功能 进行开发、测试或迁移
• delete_branch：从项目中删除现有分支
• describe_branch：获取分支详情，包括名称、ID 和父分支

SQL 查询执行：

• get_connection_string：返回数据库连接字符串
• run_sql：对指定 Neon 数据库执行单个 SQL 查询，支持读写操作
• run_sql_transaction：在单个事务中执行多个 SQL 查询
• get_database_tables：列出指定数据库中的所有表
• describe_table_schema：获取表结构定义，包括列名、数据类型和约束

数据库迁移（模式变更）：

• prepare_database_migration：启动数据库迁移流程。关键步骤是创建临时分支来安全应用和测试迁移
• complete_database_migration：将准备好的迁移应用到主分支。此操作会合并临时分支的变更并清理资源

Neon 认证：

• provision_neon_auth：为 Neon 项目配置认证基础设施的操作，通过与 Stack Auth（@stackframe/stack）集成实现

迁移管理

迁移是管理数据库模式变更的方法。Neon MCP 服务器通过"开始"（prepare_database_migration）和"提交"（complete_database_migration）命令确保 LLM 安全执行迁移。

"开始"命令接收迁移指令并在新临时分支执行。返回结果会提示 LLM 在该分支测试迁移。测试通过后，LLM 可执行"提交"命令将迁移应用到原分支。

开发指南

使用 MCP CLI 客户端开发

最便捷的开发方式是使用 mcp-client/。详见 mcp-client/README.md。

npm install
npm run build
npm run watch # 可保持此终端运行
cd mcp-client/ && NEON_API_KEY=... npm run start:mcp-server-neon

使用 Claude Desktop 开发（本地 MCP 服务器）

npm install
npm run build
npm run watch # 可保持此终端运行
node dist/index.js init $NEON_API_KEY

每次测试修改时，需重启 Claude。

测试

测试前需按 .env.example 配置 .env 文件。

npm run test