/ 目录 / 演练场 / Neon
● 官方 neondatabase 🔑 需要你的密钥

Neon

作者 neondatabase · neondatabase/mcp-server-neon

Neon 官方 MCP — 对无服务器 Postgres 进行分支操作,安全测试迁移,执行查询并从聊天中管理项目。

Neon 的官方 MCP。分支操作是核心功能:一秒钟的写时复制 fork,让你在真实数据上测试破坏性迁移而零风险。另外还有标准的项目、角色、数据库 CRUD 和 SQL 执行。

为什么要用

核心特性

实时演示

实际使用效果

neon.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "neon",
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Neon

在写时复制分支上测试破坏性 Postgres 迁移

👤 对真实数据库执行模式变更的工程师 ⏱ ~20 min intermediate

何时使用: 你有一个迁移(DROP COLUMN、大型 UPDATE、索引重建),想在生产级别的数据上运行它而不冒生产风险。

前置条件
  • Neon API key — console.neon.tech → Account → API keys
步骤
  1. 从 main 创建一个分支
    在 Neon 项目 <id> 中,从 main 分支创建名为 'test-drop-legacy' 的分支。返回新分支的连接字符串。✓ 已复制
    → 分支在 <2 秒内创建,返回连接字符串
  2. 在分支上应用迁移
    连接到新分支并运行:<粘贴迁移 SQL>。报告行计数和任何错误。✓ 已复制
    → 迁移完成;计数合理
  3. 验证,然后清理
    在更改的表上运行完整性查询。如果结果看起来正确,告诉我,我会应用到 main。然后无论如何都删除分支。✓ 已复制
    → 验证完成 + 分支已删除以避免存储费用

结果: 确保你的迁移在真实数据上有效,对生产零风险。

注意事项
  • 分支消耗的存储与你在上面写入的数据量成正比 — 测试后及时删除分支 — 写入量大的废弃分支会推高账单
  • 分支是一个快照 — 不会看到分支创建后在 main 上发生的写入 — 分支接近应用时间;或使用 Neon 时间旅行从特定时间戳分支
搭配使用: github · postgres

为集成测试启动按 PR 的临时数据库

👤 针对真实 Postgres 运行 CI 集成测试的团队 ⏱ ~15 min intermediate

何时使用: 每个 PR 需要自己的隔离数据库;SQLite mocks 不够。

步骤
  1. 创建一个以 PR 命名的分支
    在项目 <id> 中从 main 创建名为 'pr-482' 的 Neon 分支。返回连接字符串。✓ 已复制
    → 分支已就绪,返回连接字符串
  2. 对其运行测试套件
    将 DATABASE_URL 设置为该连接字符串。运行 npm run test:integration 并报告结果。✓ 已复制
    → 测试运行,通过/失败摘要
  3. 清理
    删除分支 'pr-482'。✓ 已复制
    → 分支已删除

结果: 真实数据库集成测试,几秒钟启动隔离,无共享状态污染。

注意事项
  • 较低计划中的每个项目分支限制 — 免费层限制很重要;要么升级,要么实现最大 N 个分支清理器
搭配使用: github

给予 Claude 对生产 Neon DB 的安全只读访问

👤 调试生产数据的工程师,不给模型写入权限 ⏱ ~10 min beginner

何时使用: 你想调查一个生产问题,但担心误触发的 UPDATE。

步骤
  1. 创建只读角色
    在 Neon 项目 <id> 中,创建角色 'claude_readonly',对 schema public 只有 SELECT 访问权限。返回其连接字符串。✓ 已复制
    → 角色已创建;返回连接字符串
  2. 通过 Postgres MCP 连接
    将该连接字符串与 Postgres MCP 一起使用。确认我可以运行 SELECT 但不能 INSERT。✓ 已复制
    → SELECT 有效,INSERT 错误为 'permission denied'
  3. 调查问题
    现在查询受影响 user_id 99214 的 orders 表。行状态是什么,有什么不寻常的地方吗?✓ 已复制
    → 从真实数据获得具体诊断

结果: 一个富有成效的生产调试会话,具有可证明的只读安全性。

注意事项
  • 忘记限定未来的表 — 新表没有被涵盖 — 使用 ALTER DEFAULT PRIVILEGES 确保新表自动向 claude_readonly 授予 SELECT
搭配使用: postgres

在合并前审查分支之间的模式演变

👤 DBA 和平台工程师 ⏱ ~25 min advanced

何时使用: 多个功能分支各有自己的模式更改;你想看到累积差异。

步骤
  1. 列出分支及其状态
    列出项目 <id> 的所有 Neon 分支。对于每个分支,给我一行描述其模式与 main 的差异。✓ 已复制
    → 按分支的模式差异摘要
  2. 详细比较两个分支
    对于分支 'feature-payments' vs main:diff 表、列、索引和约束。格式为 SQL 迁移。✓ 已复制
    → 可审查的 SQL diff
  3. 识别冲突
    如果 feature-payments 和 feature-auth 都被合并,它们的模式更改会冲突吗?在哪里?✓ 已复制
    → 具体冲突列表,而不是 'no obvious issues'

结果: 合并顺序加上冲突在到达 main 前已知。

注意事项
  • Diff 遗漏物化视图或存储过程内的更改 — 明确 — 要求 Claude 也 diff pg_proc 和视图定义,而不仅仅是表
搭配使用: github

组合

与其他 MCP 搭配,撬动十倍杠杆

neon + github

按 PR 的临时数据库用于 CI 测试,PR 评论显示连接信息

当 PR #482 打开时,创建 Neon 分支 'pr-482',对其运行迁移 + seeds,将连接字符串作为 PR 的私密评论发布。✓ 已复制
neon + postgres

一旦 Neon 启动分支,使用 Postgres MCP 进行更安全的只读查询

创建具有只读角色 'claude_ro' 的 Neon 分支。然后使用 Postgres MCP 与该连接字符串来调查 user-99214 问题。✓ 已复制
neon + filesystem

按顺序将本地 SQL 迁移文件应用到 Neon 分支

按名称顺序读取 /db/migrations/ 下的每个 .sql 文件。按顺序将其应用到 Neon 分支 'staging'。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_projects none 查看你的 Neon 项目 free
describe_project project_id 获取项目的概览 free
create_branch project_id, name?, parent_id?, parent_lsn? or parent_timestamp? fork 一个分支用于测试或按 PR 的数据库 branch storage billed by writes
list_branches project_id 库存分支 free
delete_branch project_id, branch_id 测试后清理 — 重要的是控制存储成本 free
get_connection_string project_id, branch_id?, role_name?, database_name? 获取限定到分支/角色/数据库的连接字符串 free
run_sql project_id, branch_id?, sql: str 对任何分支执行 SQL compute time billed
describe_table_schema project_id, branch_id?, table_name 检查表而不需要自己编写 SQL free
create_role / drop_role project_id, role_name 管理限定访问的角色 free
create_database / list_databases project_id, name 每个项目的多 DB 设置 free

成本与限制

运行它的成本

API 配额
每个计划的标准 Neon API 限制
每次调用 Token 数
大多数操作很小;SQL 结果随行数扩展 — 总是限制探索查询
费用
MCP 免费;Neon 免费层覆盖小项目,付费计划按计算小时数和存储空间计费
提示
分支在积累写入之前基本上是免费的。#1 成本惊喜是忘记的分支 — 设置清理策略或始终在使用后删除。

安全

权限、密钥、影响范围

最小权限: 尽可能将 API key 限定到单个项目
凭据存储: API key 在环境变量 NEON_API_KEY
数据出站: 调用 console.neon.tech API;SQL 流量到你的项目的区域端点
切勿授予: 不要向长期运行的 agent 授予组织范围的管理员 key

故障排查

常见错误与修复

401 Unauthorized

API key 无效或已撤销。在 console.neon.tech → Account → API keys 生成新的。

验证: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects
Branch creation fails: 'limit reached'

你已经达到计划的分支限制。删除未使用的分支或升级。

run_sql times out on a long migration

长期运行的语句可能超过默认超时。对于非常长的操作,使用带连接字符串的 psql,或拆分迁移。

Connection string works once then fails (compute paused)

Neon 免费层计算自动暂停。第一个连接唤醒它(冷启动 ~1s);后续连接很好。不要将第一次调用延迟视为失败。

替代方案

Neon 对比其他方案

替代方案何时用它替代权衡
Supabase MCP除了 Postgres,你还需要 auth、edge functions、storage更重的表面;分支限制在 Pro 计划中
Postgres MCP你只需要只读 SQL 访问权限且不使用分支没有分支/项目管理
AWS RDS via aws MCP你在 AWS 托管的 Postgres(RDS/Aurora)上没有分支;预配更重和更慢

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills