Neon MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

即時コピーオンライトブランチ — マイグレーションテストに最適
プロジェクト、ブランチ、ロール、データベースの管理
任意のブランチでSQLを実行（読み取り・書き込み両対応）
任意のブランチの接続文字列を取得
ネイティブ: 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 は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

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

Cline サイドバーの MCP Servers アイコンをクリックし、"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 はマップではなくサーバーオブジェクトの配列を使用。

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

コピーオンライトブランチで破壊的なPostgresマイグレーションをテストする

👤 本番相当のデータを持つDBに対してスキーマ変更を実行するエンジニア ⏱ ~20 min intermediate

使うタイミング： マイグレーション（DROP COLUMN、大規模UPDATE、インデックス再構築）があり、本番を危険にさらさずに本番相当のデータで実行したい場合。

前提条件

Neon APIキー — console.neon.tech → Account → API keys

フロー

mainからブランチを作成

In Neon project <id>, create a branch named 'test-drop-legacy' from the main branch. Return the connection string for the new branch.✓ コピーしました

→ 2秒以内にブランチが作成され、接続文字列が返される
ブランチにマイグレーションを適用

Connect to the new branch and run: <paste migration SQL>. Report row counts and any errors.✓ コピーしました

→ マイグレーションが完了し、行数が妥当である
検証してクリーンアップ

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.✓ コピーしました

→ 検証完了 + ストレージ課金を避けるためブランチを削除

結果： 本番へのリスクゼロで、マイグレーションが本番データで正しく動作する確信が得られます。

注意点

ブランチは書き込み量に比例してストレージを消費する — テスト後は速やかにブランチを削除してください。大量書き込みのある放置ブランチは請求額を押し上げます
ブランチはスナップショットであり、ブランチ作成後にmainで行われた書き込みは反映されない — 適用直前にブランチを作成するか、Neonのタイムトラベル機能で特定のタイムスタンプからブランチを作成してください

組み合わせ： github · postgres

PR単位の一時的なデータベースをインテグレーションテスト用に作成する

👤 本番のPostgresに対してCIインテグレーションテストを実行するチーム ⏱ ~15 min intermediate

使うタイミング： 各PRに独立したDBが必要で、SQLiteのモックでは不十分な場合。

フロー

PR名でブランチを作成

Create a Neon branch in project <id> named 'pr-482' from main. Return the connection string.✓ コピーしました

→ ブランチが準備完了、接続文字列が返される
そのブランチに対してテストスイートを実行

Set DATABASE_URL to that conn string. Run npm run test:integration and report results.✓ コピーしました

→ テストが実行され、合格/不合格のサマリーが表示される
後片付け

Delete branch 'pr-482'.✓ コピーしました

→ ブランチが削除される

結果： 数秒で起動する分離環境による本番DB対応のインテグレーションテスト。共有状態の汚染がありません。

注意点

下位プランではプロジェクトあたりのブランチ数に制限がある — 無料枠の制限に注意。アップグレードするか、最大N個のブランチスイーパーを実装してください

組み合わせ： github

Claudeに本番Neon DBへの安全な読み取り専用アクセスを付与する

👤 モデルに書き込み権限を与えずに本番データをデバッグしたいエンジニア ⏱ ~10 min beginner

使うタイミング： 本番の問題を調査したいが、誤ったUPDATEの実行が心配な場合。

フロー

読み取り専用ロールを作成

In Neon project <id>, create a role 'claude_readonly' with SELECT-only access on schema public. Return its connection string.✓ コピーしました

→ ロールが作成され、接続文字列が返される
Postgres MCPで接続

Use that conn string with the Postgres MCP. Confirm I can run SELECT but not INSERT.✓ コピーしました

→ SELECTは成功し、INSERTは'permission denied'エラーになる
問題を調査

Now query the orders table for the affected user_id 99214. What's the row state and is anything unusual?✓ コピーしました

→ 本番データからの具体的な診断結果

結果： 読み取り専用の安全性が証明された、生産的な本番デバッグセッション。

注意点

今後作成されるテーブルへのスコープ設定を忘れる — 新しいテーブルには権限が適用されない — ALTER DEFAULT PRIVILEGESを使用して、新しいテーブルがclaude_readonlyにSELECTを自動付与するようにしてください

組み合わせ： postgres

マージ前にブランチ間のスキーマ変更をレビューする

👤 DBAおよびプラットフォームエンジニア ⏱ ~25 min advanced

使うタイミング： 複数のフィーチャーブランチがそれぞれ独自のスキーマ変更を持っており、累積的な差分を確認したい場合。

フロー

ブランチとその状態を一覧表示

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

→ ブランチごとのスキーマ差分サマリー
2つのブランチを詳細に比較

For branch 'feature-payments' vs main: diff the tables, columns, indexes, and constraints. Format as a SQL migration.✓ コピーしました

→ レビュー可能なSQL差分
コンフリクトを特定

If both feature-payments and feature-auth get merged, do their schema changes conflict? Where?✓ コピーしました

→ 「明らかな問題はない」ではなく、具体的なコンフリクトリスト

結果： mainに影響する前に、マージ順序とコンフリクトが把握できます。

注意点

差分がマテリアライズドビューやストアドプロシージャ内の変更を見逃す — 明示的に指定してください — テーブルだけでなくpg_procやビュー定義の差分もClaudeに依頼してください

組み合わせ： github

組み合わせ

他のMCPと組み合わせて10倍の力を

neon + github

PR単位の一時的なDBをCIテスト用に作成し、PRコメントに接続情報を投稿

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

Neonがブランチを起動した後、Postgres MCPでより安全な読み取り専用クエリを実行

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

ローカルのSQLマイグレーションファイルをNeonブランチに順番に適用

Read every .sql file under /db/migrations/ in name order. Apply them in sequence to Neon branch 'staging'.✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
list_projects	none	Neonプロジェクトの一覧を表示	free
describe_project	project_id	プロジェクトの概要を取得	free
create_branch	project_id, name?, parent_id?, parent_lsn? or parent_timestamp?	テスト用またはPR単位のDBとしてブランチをフォーク	branch storage billed by writes
list_branches	project_id	ブランチの一覧を確認	free
delete_branch	project_id, branch_id	テスト後のクリーンアップ — ストレージコスト管理に重要	free
get_connection_string	project_id, branch_id?, role_name?, database_name?	ブランチ/ロール/DBにスコープされた接続文字列を取得	free
run_sql	project_id, branch_id?, sql: str	任意のブランチに対してSQLを実行	compute time billed
describe_table_schema	project_id, branch_id?, table_name	SQLを書かずにテーブル構造を確認	free
create_role / drop_role	project_id, role_name	スコープ付きアクセス用のロールを管理	free
create_database / list_databases	project_id, name	プロジェクト内の複数DB構成	free

コストと制限

運用コスト

APIクォータ: プランに応じた標準的なNeon APIリミット
呼び出しあたりのトークン: ほとんどの操作は小規模。SQL結果は行数に応じて増加するため、探索的なクエリには必ずLIMITを付けてください
金額: MCPは無料。Neon無料枠は小規模プロジェクトに対応し、有料プランではコンピュート時間とストレージが課金されます
ヒント: ブランチは書き込みが蓄積されるまでほぼ無料です。最大のコスト要因は放置されたブランチです — スイープポリシーを設定するか、使用後は必ず削除してください。

セキュリティ

権限、シークレット、影響範囲

最小スコープ： scope API key to a single project when possible

認証情報の保管： 環境変数NEON_API_KEYにAPIキーを格納

データ送信先： console.neon.tech APIへの呼び出し。SQLトラフィックはプロジェクトのリージョナルエンドポイントへ送信

絶対に付与しない： org-wide admin keys to long-running agents

run_sqlはデータを変更できます。本番のmainブランチに対しては、読み取り専用ロールを作成してPostgres MCP経由で接続することを推奨します。
ブランチは作成時に親からデータを継承します — 親に含まれるPIIがそのまま含まれます。機密データとして扱ってください。

トラブルシューティング

よくあるエラーと対処法

401 Unauthorized

APIキーが無効または失効しています。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'

プランのブランチ上限に達しています。不要なブランチを削除するか、プランをアップグレードしてください。

run_sql times out on a long migration

長時間実行されるステートメントはデフォルトのタイムアウトを超える場合があります。非常に長い操作には接続文字列を使ってpsqlを利用するか、マイグレーションを分割してください。

Connection string works once then fails (compute paused)

Neon無料枠のコンピュートは自動サスペンドされます。最初の接続でウェイクアップします（コールドスタート約1秒）。以降の接続は問題ありません。初回のレイテンシを障害として扱わないでください。

代替案

Neon 他との比較

代替案	代わりに使う場面	トレードオフ
Supabase MCP	Postgresに加えて認証、エッジファンクション、ストレージも必要な場合	対応範囲が広い分複雑。ブランチ機能はProプラン以上で利用可能
Postgres MCP	読み取り専用のSQLアクセスのみ必要で、ブランチ機能を使わない場合	ブランチ/プロジェクト管理機能なし
AWS RDS via aws MCP	AWSマネージドのPostgres（RDS/Aurora）を使用している場合	ブランチ機能なし。プロビジョニングがより重く低速

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る