Neon MCP Server Setup for Cursor IDE (2026): Branch, Query, and Migrate Serverless Postgres from Chat

How do you set up the Neon MCP server in Cursor? Generate a Neon API key from the Neon console, add a neon block to ~/.cursor/mcp.json pointing at the @neondatabase/mcp-server-neon package, then restart Cursor. Once connected, your AI can list projects, create database branches, and run SQL — the API key is tied to your Neon account, not a single project, so one connection covers everything you have access to.

If you've already set up a generic PostgreSQL MCP server pointed at a Neon connection string, this is a different tool solving a different problem. Keep reading before you decide which one you actually need.

Why Neon Gets Its Own MCP Server

The generic Postgres MCP server does one thing: run SQL against whatever connection string you gave it. That's fine if all you want is query access to a fixed database.

Neon's actual selling point is branching — copy-on-write database branches that spin up in seconds, isolated from your primary branch, without duplicating storage. That's a control-plane operation, not a SQL statement, so it can't be expressed through a plain connection string. The Neon-specific server exposes tools for creating branches, listing projects, checking compute status, and resetting a branch back to its parent — none of which the generic Postgres server knows exist.

When the generic Postgres server is enough: you have one database, you never branch, and you just want the AI to query and describe schema. Don't add a second MCP server for no reason.

When you want the Neon-specific one: you're testing migrations, want a disposable copy of prod-shaped data for a coding session, or you're managing multiple Neon projects and don't want to hardcode a connection string per project.

Prerequisites

Step 1: Generate a Neon API Key

1. Log into console.neon.tech
2. Go to Account settings → API keys
3. Click Generate new API key
4. Name it something like cursor-mcp
5. Copy it immediately — Neon won't show it again

This key is account-scoped, not project-scoped. It can see and act on every project your account has access to, which matters for the safety notes below.

Step 2: Add the Server to Cursor's MCP Config

Open ~/.cursor/mcp.json (or Cmd/Ctrl+Shift+P → "Open MCP Settings") and add:

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon", "start"],
      "env": {
        "NEON_API_KEY": "your-api-key-here"
      }
    }
  }
}

Save the file. No global install needed — npx fetches the package on first run.

Step 3: Restart Cursor and Verify

Quit Cursor fully and reopen it. Check View → Output → MCP to confirm the server started without errors, then try:

List my Neon projects

If it returns real project names instead of an error, the connection is live.

Real Workflows Worth Setting This Up For

Branch before a risky migration

Create a branch called "add-archived-at-column" off main, then generate and run a migration that adds an archived_at timestamp to the orders table on that branch

You get a fully isolated copy to test against — no risk to the primary branch, and no need to restore a backup if the migration is wrong.

Debug against a point-in-time copy

Neon branches can be created from a specific timestamp on the parent branch, which is the closest thing to "undo" a production database gets:

Create a branch from main as it was 6 hours ago, and check whether the orders table had the missing rows before today's deploy

Compare schema across branches

Diff the schema of the "staging-migration-test" branch against main and tell me what changed

Useful before merging a branch's changes back, since it catches drift the migration script itself might not report.

Clean up after yourself

Branches are cheap but they don't disappear on their own:

List all branches older than 7 days that aren't main, and delete the ones with no active compute endpoint

When Not to Give This Write Access

Branch creation itself is low-risk — branches are isolated, and deleting a mistaken one costs nothing. Running SQL is a different story. If your neon MCP connection can reach your primary branch, the AI can run DELETE or DROP statements against it exactly as easily as a SELECT.

Two practical guards:

Also worth knowing before you script bulk branch creation: branches share storage with their parent (cheap), but each one can have its own compute endpoint that autoscales and consumes compute time on usage-based plans. Check your plan's branch and compute limits before automating anything that creates branches in a loop.

Troubleshooting

"Invalid API key" error
Regenerate the key — Neon API keys can't be recovered once the console dialog closes, only replaced.

"Project not found"
Confirm the project actually belongs to the account that generated the key. A key from a personal account won't see projects that live under an organization unless that key was generated as a member of the org.

Branch creation fails silently
Some plans cap the number of concurrent branches. Check Project → Branches in the console for a limit warning before assuming it's a config problem.

Server doesn't appear in Cursor
Run npx -y @neondatabase/mcp-server-neon start manually in a terminal — if it errors there, it'll error the same way inside Cursor, just with less visible output.

Frequently Asked Questions

Q: What's the actual difference between the Neon MCP server and the generic Postgres MCP server?
A: The generic Postgres server only runs SQL against one connection string — it has no idea Neon exists. The Neon-specific server adds control-plane tools: create/list/delete branches, check project and compute status, and reset a branch to its parent. If you don't use branching, you don't need it.

Q: Should I let the AI create branches automatically, or confirm each one?
A: Auto-approving branch creation is reasonable since branches are cheap and isolated. Auto-approving SQL writes against main is not — most people leave query/write tools on manual confirmation and only relax branch-management tools.

Q: Does this work with Windsurf, or only Cursor?
A: The @neondatabase/mcp-server-neon package speaks standard MCP over stdio, so it works anywhere that supports an mcp.json-style config, including Windsurf and Claude Desktop. The setup steps are nearly identical — just a different config file location.

Q: Will letting the AI create branches affect my Neon bill?
A: Branch storage is copy-on-write and cheap, but each branch can carry its own compute endpoint. If you're on a usage-based plan, an endpoint that autoscales up and stays idle-but-active still burns compute time. Delete branches you're done with rather than leaving them around.

Q: Can the AI run migrations directly against my database, or only read schema?
A: Both are possible — the server doesn't distinguish read from write tools the way some database MCP servers do. That's exactly why branching matters here: point migration-running prompts at a branch, not main, until you've reviewed the result.

Related Guides