Neon MCP — Сценарии использования, Установка & Живое демо

Зачем использовать

Ключевые функции

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

Живое демо

Как выглядит на практике

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 использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "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 использует массив объектов серверов, а не map.

~/.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

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

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

Когда использовать: You have a migration (DROP COLUMN, big UPDATE, index rebuild) and you want to run it on prod-shaped data without risking prod.

Предварительные требования

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

Поток

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.✓ Скопировано

→ 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.✓ Скопировано

→ 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.✓ Скопировано

→ Verification + branch deleted to avoid storage charges

Итог: Confidence that your migration works on real data, with zero risk to prod.

Подводные камни

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

Сочетать с: github · postgres

Spin up a per-PR ephemeral database for integration tests

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

Когда использовать: Each PR needs its own isolated DB; SQLite mocks aren't enough.

Поток

Create a branch named after the PR

Create a Neon branch in project <id> named 'pr-482' from main. Return the connection string.✓ Скопировано

→ 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.✓ Скопировано

→ Tests run, pass/fail summary
Tear down

Delete branch 'pr-482'.✓ Скопировано

→ Branch removed

Итог: Real-DB integration tests with seconds-to-spin-up isolation, no shared-state contamination.

Подводные камни

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

Сочетать с: 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

Когда использовать: You want to investigate a prod issue but you're nervous about a misfired UPDATE.

Поток

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.✓ Скопировано

→ 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.✓ Скопировано

→ 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?✓ Скопировано

→ Concrete diagnosis from real data

Итог: A productive prod debug session with provable read-only safety.

Подводные камни

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

Сочетать с: postgres

Review schema evolution across branches before merging

👤 DBAs and platform engineers ⏱ ~25 min advanced

Когда использовать: Multiple feature branches each have their own schema changes; you want to see the cumulative diff.

Поток

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.✓ Скопировано

→ 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.✓ Скопировано

→ Reviewable SQL diff
Identify conflicts

If both feature-payments and feature-auth get merged, do their schema changes conflict? Where?✓ Скопировано

→ Specific conflict list, not 'no obvious issues'

Итог: Merge order plus conflicts known before they hit main.

Подводные камни

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

Сочетать с: github

Комбинации

Сочетайте с другими MCP — эффект x10

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.✓ Скопировано

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.✓ Скопировано

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'.✓ Скопировано

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать	Стоимость
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

Стоимость и лимиты

Во что обходится

Квота API: Standard Neon API limits per plan
Токенов на вызов: Most ops are small; SQL results scale with row count — always LIMIT exploratory queries
Деньги: MCP free; Neon Free tier covers small projects, paid plans bill compute-hours and storage
Совет: Branches are nearly free until they accumulate writes. The #1 cost surprise is forgotten branches — set a sweep policy or always delete after use.

Безопасность

Права, секреты, радиус поражения

Минимальные скоупы: scope API key to a single project when possible

Хранение учётных данных: API key in env var NEON_API_KEY

Исходящий трафик: Calls to console.neon.tech API; SQL traffic to your project's regional endpoint

Никогда не давайте: 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.

Устранение неполадок

Частые ошибки и исправления

401 Unauthorized

API key invalid or revoked. Generate new at 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'

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.

Альтернативы

Neon в сравнении

Альтернатива	Когда использовать	Компромисс
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

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills