Neon MCP Server快速上手:3步连接Cursor与Claude Code,对话式创建你的第一个Postgres项目

原创2026-11-04 20:32:541,928 阅读

Neon MCP Server快速上手:3步连接Cursor与Claude Code,对话式创建你的第一个Postgres项目

Neon MCP Server 是一款开源的 MCP Server(Model Context Protocol 服务器),它让你用自然语言就能管理 Neon 上的 Postgres 数据库:创建项目、建表、执行 SQL、跑迁移,全程不需要手写 API 调用。本文带你用 3 步把 Neon MCP Server 接入 Cursor 或 Claude Code,然后"对话式"地创建你的第一个 Postgres 项目。

Neon MCP Server 连接 Cursor 与 Claude Code 的快速上手指南封面

为什么需要 Neon MCP Server?

对新手来说,管理 Postgres 数据库通常意味着:注册云服务、申请 API Key、阅读 REST 文档、拼接复杂的请求参数。而 Neon MCP Server 把这些统统翻译成"说人话":

传统方式 使用 Neon MCP Server 后
手写 POST /projects 请求创建项目 直接说:"帮我创建一个叫 my-database 的数据库"
手动拼接 migration 文件并执行 说:"给 users 表加一个 created_at 字段"
登录控制台看项目列表 问:"总结我所有的 Neon 项目里有什么数据"

它的核心能力(详见 README.md):

  • ✅ 自然语言交互:通过对话管理项目、分支、计算端点与数据
  • ✅ 免写 SQL / API:自动把请求转成 Neon API 调用
  • ✅ 安全的数据库迁移:先在临时分支上试跑,确认无误再合并到主分支
  • ✅ OAuth 一键授权:不用手动管理 API Key,浏览器授权即可

准备工作(Prerequisites)

开始 3 步之前,请确认你拥有:

  1. 一个 MCP 客户端:Cursor 或 Claude Code(任选其一即可)
  2. 一个 Neon 账号(免费即可,在 Neon Console 注册)
  3. Node.js(客户端本地执行 npx 命令时需要)

💡 如果开启了 IP Allow 白名单,记得把 mcp.neon.tech 的两个静态 IP(34.192.103.46 和 23.22.233.166)加入白名单,否则连接会被拒绝。

3 步连接 Cursor 与 Claude Code

第 1 步:选择接入方式(推荐 OAuth)

Neon MCP Server 提供三种接入方式,本文推荐最简单、无需管理 API Key 的 Remote Hosted + OAuth 方式,服务器地址为 https://mcp.neon.tech/mcp。

在 Cursor 或 Claude Code 的工作目录中执行(一条命令即可被自动发现的 MCP 客户端识别):

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"

URL 中的 category 参数用于按需开放工具类别(projects 项目、branches 分支、endpoints 计算端点、querying 查询、schema 表结构)。如果你只想要更少的工具,也可以直接连接不带参数的 https://mcp.neon.tech/mcp 获得全部类别,或只保留 ?category=querying&category=schema。

第 2 步:完成 OAuth 授权

重启或刷新你的 MCP 客户端后,浏览器会自动弹出 Neon 的授权页面(授权流程由 app/callback/route.ts 与 lib/oauth/client.ts 实现)。你会看到如下界面:

Neon MCP Server OAuth授权页面:选择允许Cursor或Claude Code访问的Neon项目

页面上可以看到:

  • App details:客户端的回调地址等身份信息,确认是你本机发起的授权
  • Choose access:选择授权范围——"All projects you can access"(全部项目)或指定某个 project_id
  • Approve:点击即完成授权,客户端自动拿到访问令牌

如果你希望限制 AI 的权限(比如只允许查询和查看表结构),可以在连接 URL 上加 readonly=true&category=querying&category=schema,授权页会变成只读确认样式:

Neon MCP Server只读授权确认页:限定Querying和Schema类别的访问权限

第 3 步:验证连接成功

回到 Cursor 或 Claude Code,确认 MCP 服务器列表中 Neon 已连接(图标点亮)。你也可以不依赖客户端,直接用命令行预览当前 URL 会暴露哪些工具:

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

能返回工具清单 JSON,说明链路完全通畅。🎉

对话式创建你的第一个 Postgres 项目

连接成功后,真正的"魔法"开始了。在 Cursor 的 Composer 或 Claude Code 的对话框里,直接说:

"创建一个名为 my-database 的 Postgres 数据库,再建一张 users 表,包含 id、name、email、password 四列。"

MCP 客户端会依次调用 create_project、get_connection_string、run_sql 等工具完成整套操作。你还可以继续说:

  • "给 my-project 的 users 表加一个 created_at 列(跑一次迁移)"
  • "总结我所有 Neon 项目里各有什么数据"
  • "找出 my-database 里最慢的 5 条查询"

其中迁移功能值得特别关注:prepare_database_migration 会先创建一个临时分支应用变更,你验证通过后 complete_database_migration 再合并回主分支——相当于给 Schema 变更加了一道"安全闸门"。

权限控制速查:URL 参数一览

所有权限都由 MCP URL 上的查询参数控制,改 URL 并重新授权即可生效:

参数 作用 示例
readonly 开启只读模式(禁用建项目/分支等写操作) ?readonly=true
category 限制可暴露的工具类别 ?category=querying&category=schema
projectId 把全部操作限定在单个项目内 ?projectId=proj-123
roleName 让所有 SQL 以指定 Postgres 角色执行 ?roleName=app_reader

典型的"只读 + 单项目 + 指定角色"组合:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id&roleName=app_reader"
    }
  }
}

⚠️ 安全提示:MCP Server 具备强大的数据库管理权限,执行前请始终复核 AI 请求的操作。官方建议仅用于本地开发与 IDE 集成场景,不建议在生产环境直接启用。

项目源码结构一览

想深入了解实现细节?仓库主要目录如下:

开发相关命令(pnpm 通过 Corepack 提供):pnpm dev 本地启动、pnpm test:unit 跑单元测试、pnpm test:e2e 跑端到端测试。

小结

至此你已经掌握了 Neon MCP Server 快速上手 的完整路径:

  1. npx add-mcp 一行命令注册远程 MCP 服务器
  2. 浏览器 OAuth 授权,按需选择项目与只读权限
  3. 用自然语言创建第一个 Postgres 项目并管理迁移

把"调 API"变成"说句话",这就是 MCP 给 AI 编程工作流带来的改变。去 Cursor 或 Claude Code 里试试吧!

登录后查看全文
mcp-server-neon