Neon MCP Server快速上手:3步连接Cursor与Claude Code,对话式创建你的第一个Postgres项目
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?
对新手来说,管理 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 步之前,请确认你拥有:
- 一个 MCP 客户端:Cursor 或 Claude Code(任选其一即可)
- 一个 Neon 账号(免费即可,在 Neon Console 注册)
- 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 实现)。你会看到如下界面:
页面上可以看到:
- App details:客户端的回调地址等身份信息,确认是你本机发起的授权
- Choose access:选择授权范围——"All projects you can access"(全部项目)或指定某个
project_id - Approve:点击即完成授权,客户端自动拿到访问令牌
如果你希望限制 AI 的权限(比如只允许查询和查看表结构),可以在连接 URL 上加 readonly=true&category=querying&category=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 集成场景,不建议在生产环境直接启用。
项目源码结构一览
想深入了解实现细节?仓库主要目录如下:
- app/api/[transport]/route.ts:核心
/mcpStreamable HTTP 端点 - app/authorize/、app/api/token/route.ts:OAuth 授权与令牌端点
- mcp/tools/:工具定义、注册与权限过滤(grant-filter)
- mcp/oauth/consent-dialog.ts:上文授权页面的对话框逻辑
- mcp/server/index.ts:MCP Server 入口
- lib/oauth/:OAuth 客户端、重定向 URI 等基础设施
开发相关命令(pnpm 通过 Corepack 提供):pnpm dev 本地启动、pnpm test:unit 跑单元测试、pnpm test:e2e 跑端到端测试。
小结
至此你已经掌握了 Neon MCP Server 快速上手 的完整路径:
npx add-mcp一行命令注册远程 MCP 服务器- 浏览器 OAuth 授权,按需选择项目与只读权限
- 用自然语言创建第一个 Postgres 项目并管理迁移
把"调 API"变成"说句话",这就是 MCP 给 AI 编程工作流带来的改变。去 Cursor 或 Claude Code 里试试吧!


