Neon MCP — Use Cases, Install & Live Demo

Why use it

Key features

Instant copy-on-write branches — perfect for testing migrations
Project, branch, role, and database management
Run SQL on any branch (read or write)
Connection string retrieval for any branch
Native: built and maintained by Neon

Live Demo

What it looks like in practice

neon.replay ▶ ready

0/0

Install

Pick your client

~/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"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "neon": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@neondatabase/mcp-server-neon"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Neon

Test a destructive Postgres migration on a copy-on-write branch

👤 Engineers running schema changes against a real-data DB ⏱ ~20 min intermediate

When to use: You have a migration (DROP COLUMN, big UPDATE, index rebuild) and you want to run it on prod-shaped data without risking prod.

Prerequisites

Neon API key — console.neon.tech → Account → API keys

Flow

Create a branch from main

In Neon project <id>, create a branch named 'test-drop-legacy' from the main branch. Return the connection string for the new branch.✓ Copied

→ Branch created in <2 seconds, conn string returned
Apply the migration on the branch

Connect to the new branch and run: <paste migration SQL>. Report row counts and any errors.✓ Copied

→ Migration completes; counts make sense
Verify, then clean up

Run sanity queries on the changed tables. If results look correct, tell me and I'll apply to main. Then delete the branch either way.✓ Copied

→ Verification + branch deleted to avoid storage charges

Outcome: Confidence that your migration works on real data, with zero risk to prod.

Pitfalls

Branch consumes storage proportional to how much you write on it — Delete branches promptly after testing — abandoned branches with heavy writes drive up bill
Branch is a snapshot — doesn't see writes that happen on main after branch creation — Branch close to apply time; or use Neon time-travel to branch from a specific timestamp

Combine with: github · postgres

Spin up a per-PR ephemeral database for integration tests

👤 Teams running CI integration tests against real Postgres ⏱ ~15 min intermediate

When to use: Each PR needs its own isolated DB; SQLite mocks aren't enough.

Flow

Create a branch named after the PR

Create a Neon branch in project <id> named 'pr-482' from main. Return the connection string.✓ Copied

→ Branch ready, conn string returned
Run the test suite against it

Set DATABASE_URL to that conn string. Run npm run test:integration and report results.✓ Copied

→ Tests run, pass/fail summary
Tear down

Delete branch 'pr-482'.✓ Copied

→ Branch removed

Outcome: Real-DB integration tests with seconds-to-spin-up isolation, no shared-state contamination.

Pitfalls

Branch limits per project on lower plans — Free tier limits matter; either upgrade or implement a max-N-branches sweeper

Combine with: github

Give Claude safe read-only access to a production Neon DB

👤 Engineers debugging prod data without giving the model write power ⏱ ~10 min beginner

When to use: You want to investigate a prod issue but you're nervous about a misfired UPDATE.

Flow

Create a read-only role

In Neon project <id>, create a role 'claude_readonly' with SELECT-only access on schema public. Return its connection string.✓ Copied

→ Role created; conn string returned
Connect via Postgres MCP

Use that conn string with the Postgres MCP. Confirm I can run SELECT but not INSERT.✓ Copied

→ SELECT works, INSERT errors with 'permission denied'
Investigate the issue

Now query the orders table for the affected user_id 99214. What's the row state and is anything unusual?✓ Copied

→ Concrete diagnosis from real data

Outcome: A productive prod debug session with provable read-only safety.

Pitfalls

Forgetting to scope future tables — new tables aren't covered — Use ALTER DEFAULT PRIVILEGES to ensure new tables grant SELECT to claude_readonly automatically

Combine with: postgres

Review schema evolution across branches before merging

👤 DBAs and platform engineers ⏱ ~25 min advanced

When to use: Multiple feature branches each have their own schema changes; you want to see the cumulative diff.

Flow

List branches and their states

List all Neon branches for project <id>. For each, give me a one-line description of how its schema differs from main.✓ Copied

→ Per-branch schema delta summary
Compare two branches in detail

For branch 'feature-payments' vs main: diff the tables, columns, indexes, and constraints. Format as a SQL migration.✓ Copied

→ Reviewable SQL diff
Identify conflicts

If both feature-payments and feature-auth get merged, do their schema changes conflict? Where?✓ Copied

→ Specific conflict list, not 'no obvious issues'

Outcome: Merge order plus conflicts known before they hit main.

Pitfalls

Diff misses changes inside materialized views or stored procs — Be explicit — ask Claude to also diff pg_proc and view definitions, not just tables

Combine with: github

Combinations

Pair with other MCPs for X10 leverage

neon + github

Per-PR ephemeral DB for CI tests, with PR comments showing connection info

When PR #482 opens, create a Neon branch 'pr-482', run migrations + seeds against it, post the conn string as a private comment on the PR.✓ Copied

neon + postgres

Use Postgres MCP for safer read-only querying once Neon spins up the branch

Create a Neon branch with read-only role 'claude_ro'. Then use Postgres MCP with that conn string to investigate the user-99214 issue.✓ Copied

neon + filesystem

Apply local SQL migration files to a Neon branch in order

Read every .sql file under /db/migrations/ in name order. Apply them in sequence to Neon branch 'staging'.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_projects	none	See your Neon projects	free
describe_project	project_id	Get an overview of a project	free
create_branch	project_id, name?, parent_id?, parent_lsn? or parent_timestamp?	Fork a branch for testing or per-PR DBs	branch storage billed by writes
list_branches	project_id	Inventory branches	free
delete_branch	project_id, branch_id	Clean up after testing — important to control storage cost	free
get_connection_string	project_id, branch_id?, role_name?, database_name?	Get a conn string scoped to a branch/role/db	free
run_sql	project_id, branch_id?, sql: str	Execute SQL against any branch	compute time billed
describe_table_schema	project_id, branch_id?, table_name	Inspect a table without writing the SQL yourself	free
create_role / drop_role	project_id, role_name	Manage roles for scoped access	free
create_database / list_databases	project_id, name	Multi-DB-per-project setups	free

Cost & Limits

What this costs to run

API quota: Standard Neon API limits per plan
Tokens per call: Most ops are small; SQL results scale with row count — always LIMIT exploratory queries
Monetary: MCP free; Neon Free tier covers small projects, paid plans bill compute-hours and storage
Tip: Branches are nearly free until they accumulate writes. The #1 cost surprise is forgotten branches — set a sweep policy or always delete after use.

Security

Permissions, secrets, blast radius

Minimum scopes: scope API key to a single project when possible

Credential storage: API key in env var NEON_API_KEY

Data egress: Calls to console.neon.tech API; SQL traffic to your project's regional endpoint

Never grant: org-wide admin keys to long-running agents

run_sql can mutate. For prod main branch, prefer creating a read-only role and connecting via Postgres MCP instead.
Branches inherit data from parent at creation time — they contain whatever PII the parent contains. Treat them as sensitive.

Troubleshooting

Common errors and fixes

401 Unauthorized

API key invalid or revoked. Generate new at console.neon.tech → Account → API keys.

Verify: curl -H 'Authorization: Bearer $NEON_API_KEY' https://console.neon.tech/api/v2/projects

Branch creation fails: 'limit reached'

You've hit your plan's branch limit. Delete unused branches or upgrade.

run_sql times out on a long migration

Long-running statements may exceed default timeout. Use psql with the connection string for very long ops, or split the migration.

Connection string works once then fails (compute paused)

Neon free-tier compute auto-suspends. First connection wakes it (cold start ~1s); subsequent connections are fine. Don't treat first-call latency as failure.

Alternatives

Neon vs others

Alternative	When to use it instead	Tradeoff
Supabase MCP	You want auth, edge functions, storage in addition to Postgres	Heavier surface; branching gated to Pro plan
Postgres MCP	You only need read-only SQL access and don't use branching	No branch/project management
AWS RDS via aws MCP	You're on AWS-managed Postgres (RDS/Aurora)	No branching; provisioning is heavier and slower

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills