Neon

Neon MCP サーバー

Neon MCP サーバーは、Neon 上の Lakebase Postgres データベースと自然言語で対話できるようにするオープンソースツールです。

Model Context Protocol（MCP）は、大規模言語モデル（LLM）と外部システム間のコンテキストを管理するために設計された標準化プロトコルです。このリポジトリは、Neon 用のリモート MCP サーバーを提供します。

Neon の MCP サーバーは、自然言語リクエストと Neon API の間のブリッジとして機能します。MCP 上に構築されており、リクエストを必要な API 呼び出しに変換して、プロジェクトやブランチの作成、クエリの実行、データベースマイグレーションの実行などのタスクをシームレスに管理できるようにします。

Neon MCP サーバーの主な機能は次のとおりです。

• 自然言語による対話: 直感的で会話形式のコマンドを使用して Neon データベースを管理します。
• 簡素化されたデータベース管理: SQL を記述したり、Neon API を直接使用したりせずに複雑な操作を実行します。
• 非開発者向けのアクセシビリティ: さまざまな技術的背景を持つユーザーが Neon データベースと対話できるようにします。
• データベースマイグレーションのサポート: 自然言語で開始されたデータベーススキーマ変更に Neon のブランチ機能を活用します。

たとえば、Claude Code や任意の MCP クライアントでは、自然言語を使用して Neon で次のようなことを実行できます。

• Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
• I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
• Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Neon MCP サーバーのセキュリティに関する考慮事項
Neon MCP サーバーは、自然言語リクエストを通じて強力なデータベース管理機能を提供します。実行前に、LLM によって要求されたアクションを常に確認し、承認してください。 承認されたユーザーとアプリケーションのみが Neon MCP サーバーにアクセスできるようにしてください。

Neon MCP サーバーは、ローカル開発および IDE 統合のみを目的としています。本番環境での Neon MCP サーバーの使用は推奨しません。 偶発的または不正な変更につながる可能性のある強力な操作を実行できます。

詳細については、MCP セキュリティガイダンス → を参照してください。

Neon MCP サーバーのセットアップ

Neon MCP サーバーをセットアップするには、いくつかのオプションがあります。

1. API キーによるクイックセットアップ（Cursor、VS Code、Claude Code）: neon@latest init を実行して、Neon の MCP サーバー、エージェントスキル、VS Code 拡張機能を 1 つのコマンドで自動構成します。
2. リモート MCP サーバー（OAuth ベースの認証）: OAuth を使用した認証で Neon の管理対象 MCP サーバーに接続します。この方法は、API キーを管理する必要がないため、より便利です。さらに、リリースされるとすぐに最新の機能と改善点が自動的に適用されます。
3. リモート MCP サーバー（API キーベースの認証）: API キーを使用した認証で Neon の管理対象 MCP サーバーに接続します。この方法は、OAuth が利用できない環境でリモートエージェントを Neon に接続する場合に便利です。さらに、リリースされるとすぐに最新の機能と改善点が自動的に適用されます。

前提条件

• MCP クライアントアプリケーション。
• Neon アカウント。
• Node.js（>= v18.0.0）: nodejs.org からダウンロードします。
• IP 許可リストが有効な場合は、34.192.103.46 と 23.22.233.166 を許可リストに追加します（mcp.neon.tech 静的 IP）。

開発には Node.js 22+ が必要です（pnpm は Corepack 経由で提供されます — 有効化するには corepack enable を実行してください）。

オプション 1. API キーによるクイックセットアップ

API キーを手動で作成したくない場合。

neon@latest init を実行して、Neon の MCP サーバーを 1 つのコマンドで自動構成します。

npx neon@latest init

これは Cursor、VS Code（GitHub Copilot）、Claude Code で動作します。OAuth で認証し、Neon API キーを作成して、エディターを自動的に構成します。

オプション 2. リモートホスト型 MCP サーバー（OAuth ベースの認証）

OAuth を使用した認証で Neon の管理対象 MCP サーバーに接続します。これは最も簡単なセットアップで、このサーバーのローカルインストールは不要で、クライアントに Neon API キーを構成する必要もありません。

次のコマンドを実行して、ワークスペース内の検出されたすべてのエージェントとエディターに Neon MCP サーバーを追加します。

npx add-mcp https://mcp.neon.tech/mcp

-g フラグを追加すると、プロジェクトスコープではなくグローバル MCP サーバーリストに Neon MCP サーバーが追加されます。

または、クライアントの MCP サーバー構成ファイル（例: mcp.json、mcp_config.json）に次の「Neon」エントリを追加することもできます。

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Kiro MCP 構成ファイル（グローバル用は ~/.kiro/settings/mcp.json、プロジェクトスコープ用は .kiro/settings/mcp.json）に次の内容を追加します。

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

または、この README の上部にあるワンクリックインストールボタンを使用します。詳細については、Kiro MCP ドキュメントを参照してください。

• MCP クライアントを再起動または更新します。
• ブラウザで OAuth ウィンドウが開きます。プロンプトに従って、MCP クライアントが Neon アカウントにアクセスすることを承認します。

OAuth ベースの認証では、MCP サーバーはデフォルトで個人の Neon アカウントのプロジェクトで動作します。組織に属するプロジェクトにアクセスまたは管理するには、MCP クライアントへのプロンプトで org_id または project_id のいずれかを明示的に指定する必要があります。

オプション 3. リモートホスト型 MCP サーバー（API キーベースの認証）

リモート MCP サーバーは、クライアントがサポートしている場合、Authorization ヘッダーでの API キーを使用した認証もサポートしています。

Neon コンソールで Neon API キーを作成します。次に、次のコマンドを実行して、ワークスペース内の検出されたすべてのエージェントとエディターに Neon MCP サーバーを追加します。

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

または、クライアントの MCP サーバー構成ファイル（例: mcp.json、mcp_config.json）に次の「Neon」エントリを追加することもできます。

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

組織の API キーを指定すると、組織のプロジェクトのみにアクセスが制限されます。

スコープと読み取り専用モード

Neon MCP は OAuth スコープ read、write、* をサポートしています（* は両方を意味します）。MCP クライアントはこれらのスコープを直接要求するか、OAuth 権限 UI で選択することができます。

読み取り専用モードは、利用可能なツールを制限し、プロジェクトやブランチの作成、マイグレーションの実行などの書き込み操作を無効にします。読み取り専用ツールには、プロジェクトの一覧表示、スキーマの説明、データのクエリ、パフォーマンスメトリクスの表示が含まれます。

読み取り専用モードは 2 つの方法で設定できます。

1. OAuth スコープの選択（推奨）: OAuth で、承認 UI のフルアクセスのチェックを外して読み取り専用を選択します。
2. readonly クエリパラメータ: MCP サーバー URL に ?readonly=true を追加します。

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

クエリパラメータの動作:

• API キーフロー: 読み取り専用モードを有効にするには readonly=true を使用します（このフローでは OAuth スコープの交換はありません）。
• OAuth フロー: readonly=true は OAuth スコープを上書きします。これがない場合、読み取り専用は OAuth 同意 UI で選択されたスコープによって決定されます。

レガシー HTTP ヘッダー x-read-only もフォールバックとしてサポートされています（クエリパラメータよりも優先度が低い）。

注: 読み取り専用モードは、利用可能な_ツール_を制限します。さらに、run_sql ツールは読み取り専用クエリの場合にのみ利用可能です。

アクセス制御のための URL クエリパラメータ

付与コンテキスト（スコープカテゴリ、プロジェクトスコープ、読み取り専用モード）は、MCP サーバー URL の URL クエリパラメータで構成されます。構成はすべてのリクエストに同行し、すぐに有効になります — 再認証は不要です。

パラメータ	説明	例
readonly	読み取り専用モードを有効にする（true/false）	?readonly=true
category	特定のツールカテゴリに制限する（繰り返しまたは CSV）	?category=querying&category=schema
projectId	すべての操作を単一のプロジェクトにスコープする	?projectId=proj-123

読み取り専用 + プロジェクトスコープの例:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

カテゴリフィルタリングの例（クエリとスキーマツールのみ）:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

任意の構成でどのツールが表示されるかは、/api/list-tools エンドポイントを使用してプレビューできます（認証は不要です）。

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

読み取り専用モードで利用可能なツール

• list_projects、list_shared_projects、describe_project、list_organizations
• describe_branch、list_branch_computes、compare_database_schema
• run_sql、run_sql_transaction、get_database_tables、describe_table_schema
• list_slow_queries、explain_sql_statement
• get_connection_string
• get_neon_auth_config
• query_logs、list_log_fields、list_log_field_values
• search、fetch、list_docs_resources、get_doc_resource

書き込みアクセスが必要なツール:

• create_project、delete_project
• create_branch、delete_branch、reset_from_parent
• provision_neon_auth、configure_neon_auth、provision_neon_data_api
• prepare_database_migration、complete_database_migration
• prepare_query_tuning、complete_query_tuning

Server-Sent Events（SSE）トランスポート（非推奨）

MCP は 2 つのリモートサーバートランスポートをサポートしています: 非推奨の Server-Sent Events（SSE）と、より新しい推奨の Streamable HTTP です。お使いの LLM クライアントがまだ Streamable HTTP をサポートしていない場合は、エンドポイントを https://mcp.neon.tech/mcp から https://mcp.neon.tech/sse に切り替えて SSE を使用できます。

次のコマンドを実行して、SSE トランスポートを使用してワークスペース内の検出されたすべてのエージェントとエディターに Neon MCP サーバーを追加します。

npx add-mcp https://mcp.neon.tech/sse --type sse

リモートサーバーアーキテクチャ

リモートサーバーは、Vercel 上の Next.js App Router アプリケーションとして mcp.neon.tech で実行されます。

[!NOTE] ルートの / パスは Neon MCP サーバードキュメントにリダイレクトされます。ランディングページはありません。

コア実装領域:

• app/api/[transport]/route.ts: Streamable HTTP（/mcp）および SSE（/sse）用の MCP トランスポートエンドポイント
• app/api/authorize/、app/callback/、app/api/token/、app/api/revoke/: OAuth フローエンドポイント
• app/.well-known/: OAuth ディスカバリメタデータエンドポイント
• mcp/: MCP サーバー、ツール、ハンドラー、アナリティクス、Sentry 統合
• lib/: Next.js 互換ヘルパー（OAuth、構成、エラーハンドリング）
• mcp/utils/read-only.ts: 読み取り専用モードとスコープの処理

ガイド

• Neon MCP サーバーガイド
• MCP クライアントを Neon に接続する
• Neon MCP サーバーでの Cursor
• Neon MCP サーバーでの Claude Code
• Neon MCP サーバーでの Claude Desktop
• Neon MCP サーバーでの Cline
• Neon MCP サーバーでの Windsurf
• Neon MCP サーバーでの Zed

機能

サポートされているツール

Neon MCP サーバーは、MCP クライアントに「ツール」として公開される次のアクションを提供します。これらのツールを使用して、自然言語コマンドで Neon プロジェクトとデータベースと対話できます。

ツールのスコープメタデータ

各ツール定義には、付与ベースのツールフィルタリングと同意 UX に使用される scope カテゴリが含まれています。現在のカテゴリは次のとおりです。

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• observability
• docs
• null（スコープカテゴリのないツール）

注:

• compare_database_schema は schema に分類されています。
• provision_neon_data_api は data_api に分類されています（neon_auth とは別）。
• 読み取り専用の強制は依然として readOnlySafe とサーバー側の読み取り専用ロジックに依存しています。scope はカテゴリのメタデータであり、独立した読み取り/書き込みスイッチではありません。
• プロジェクトスコープモード（?projectId=...）では、search と fetch は利用できません。

プロジェクト管理:

• list_projects: アカウント内の最初の10個のNeonプロジェクトを一覧表示し、各プロジェクトの概要を提供します。特定のプロジェクトが見つからない場合は、limit パラメータに大きい値を渡して制限を増やしてください。
• list_shared_projects: 現在のユーザーと共有されているNeonプロジェクトを一覧表示します。検索パラメータと返されるプロジェクト数の制限（デフォルト: 10）をサポートします。
• describe_project: 特定のNeonプロジェクトの詳細情報（ID、名前、関連するブランチとデータベース）を取得します。
• create_project: Neonアカウントに新しいNeonプロジェクトを作成します。プロジェクトはブランチ、データベース、ロール、コンピュートのコンテナとして機能します。
• delete_project: 既存のNeonプロジェクトと、それに関連するすべてのリソースを削除します。
• list_organizations: 現在のユーザーがアクセス権を持つすべての組織を一覧表示します。必要に応じて、search パラメータを使用して組織名またはIDでフィルタリングできます。

ブランチ管理:

• create_branch: 指定されたNeonプロジェクト内に新しいブランチを作成します。開発、テスト、マイグレーションのために Neon's branching 機能を活用します。
• delete_branch: Neonプロジェクトから既存のブランチを削除します。
• describe_branch: 特定のブランチの詳細（名前、ID、親ブランチなど）を取得します。
• list_branch_computes: プロジェクトまたは特定のブランチのコンピュートエンドポイントを一覧表示します。コンピュートID、タイプ、サイズ、最終アクティブ時刻、オートスケーリング情報が含まれます。
• compare_database_schema: 子ブランチとその親ブランチ間のスキーマ差分を表示します。
• reset_from_parent: 現在のブランチを親の状態にリセットし、ローカルの変更を破棄します。ブランチに子がある場合は自動的にバックアップとして保持し、カスタム名でリクエストに応じて保持することもできます。

SQLクエリ実行:

• get_connection_string: データベース接続文字列を返します。
• run_sql: 指定されたNeonデータベースに対して単一のSQLクエリを実行します。読み取り操作と書き込み操作の両方をサポートします。
• run_sql_transaction: Neonデータベースに対して単一のトランザクション内で一連のSQLクエリを実行します。
• get_database_tables: 指定されたNeonデータベース内のすべてのテーブルを一覧表示します。
• describe_table_schema: 特定のテーブルのスキーマ定義を取得し、列、データ型、制約を詳しく表示します。

データベースマイグレーション（スキーマ変更）:

• prepare_database_migration: データベースマイグレーションプロセスを開始します。重要なのは、メインブランチに影響を与える前に、マイグレーションを安全に適用・テストするための一時ブランチを作成することです。
• complete_database_migration: 準備されたデータベースマイグレーションを確定し、メインブランチに適用します。この操作は一時マイグレーションブランチからの変更をマージし、一時リソースをクリーンアップします。

SQLクエリと最適化:

• list_slow_queries: データベース内で最も遅いクエリを見つけることで、パフォーマンスのボトルネックを特定します。pg_stat_statements 拡張機能が必要です。
• explain_sql_statement: SQLクエリの詳細な実行計画を提供し、パフォーマンスのボトルネックを特定するのに役立ちます。
• prepare_query_tuning: クエリのパフォーマンスを分析し、インデックス作成などの最適化を提案します。これらの最適化を安全にテストするための一時ブランチを作成します。
• complete_query_tuning: 最適化をメインブランチに適用するか破棄することで、クエリチューニングを確定します。一時チューニングブランチをクリーンアップします。

Neon認証:

• provision_neon_auth: NeonプロジェクトにNeon Authをプロビジョニングします。認証プロバイダーとの統合を作成することで、開発者が認証インフラストラクチャを簡単にセットアップできるようにします。
• configure_neon_auth: ブランチの既存のNeon Auth統合を設定します — 信頼できるオリジン、localhostアクセス、認証方法、OAuthプロバイダー、トランザクションメールプロバイダーを管理します。
• get_neon_auth_config: ブランチの完全なNeon Auth設定を読み取ります。統合メタデータと設定可能なオプションが含まれます（シークレットはマスクされます）。

Neon Data API:

• provision_neon_data_api: HTTPベースのデータベースアクセスのためにNeon Data APIをプロビジョニングします。Neon Authまたは外部JWKSプロバイダーによるオプションのJWT認証をサポートします。

検索と発見:

• search: クエリに一致する組織、プロジェクト、ブランチを横断して検索します。ID、タイトル、Neon Consoleへの直接リンクを返します。
• fetch: ID（通常は検索ツールから取得）を使用して、特定の組織、プロジェクト、またはブランチの詳細情報を取得します。

可観測性:

• query_logs: 構造化フィルタ（ソース、サービス名、重大度、時間枠）を使用して、Neonサーバーレス関数やその他のサービスが出力するログをクエリします。ログはOpenTelemetryベースです。
• list_log_fields: ブランチでフィルタリングできるログフィールド（ラベル）を一覧表示します。例: service_name、severity_text、scope_name。query_logs の前に使用します。
• list_log_field_values: ブランチと時間枠内のログフィールドの個別値を一覧表示し、query_logs に渡す具体的な値を発見します。

ドキュメントとリソース:

• list_docs_resources: https://neon.com/docs/llms.txt からインデックスを取得して、利用可能なすべてのNeonドキュメントページを一覧表示します。get_doc_resource ツールを使用して個別に取得できるページURLとタイトルを返します。
• get_doc_resource: 特定のNeonドキュメントページをMarkdownコンテンツとして取得します。最初に list_docs_resources ツールを使用して利用可能なページスラッグを発見し、次にそのスラッグをこのツールに渡します。

マイグレーション

マイグレーションは、データベーススキーマへの変更を時間経過とともに管理する方法です。Neon MCPサーバーを使用すると、LLMは個別の「Start」（prepare_database_migration）コマンドと「Commit」（complete_database_migration）コマンドを使用して、マイグレーションを安全に実行できます。

「Start」コマンドはマイグレーションを受け入れ、新しい一時ブランチで実行します。戻ると、このコマンドはLLMにこのブランチでマイグレーションをテストすべきであることを示します。その後、LLMは「Commit」コマンドを実行して、マイグレーションを元のブランチに適用できます。

開発

このプロジェクトはCorepackでピン留めされた pnpm をパッケージマネージャーとして使用します。

プロジェクト構造

MCPサーバーコードはリポジトリのルートにあり、mcp.neon.tech のVercelにデプロイされたNext.jsアプリケーションです。

corepack enable
pnpm install

ローカル開発

# Start the Next.js dev server (for the remote MCP server)
pnpm dev

リンティングと型チェック

pnpm lint
pnpm typecheck

環境変数

リモートサーバーの実行に必要:

変数	説明
SERVER_HOST	サーバーURL（デフォルトは VERCEL_URL）
UPSTREAM_OAUTH_HOST	Neon OAuthプロバイダーURL
CLIENT_ID	OAuthクライアントID
CLIENT_SECRET	OAuthクライアントシークレット
COOKIE_SECRET	署名付きCookie用のシークレット
KV_URL	Vercel KV（Upstash Redis）URL
OAUTH_DATABASE_URL	トークン保存用のPostgres URL

任意:

変数	説明
LOG_LEVEL	Winstonログレベル: error、warn、info（デフォルト）、debug、verbose、silly

テストピラミッド

すべてのテストはリポジトリのルートから実行されます。

# Unit tests
pnpm test:unit

# Integration tests
pnpm test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Full end-to-end suite
pnpm test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm test

テスト戦略:

• トランスポート/プロトコルとユーザーに表示される動作には E2E を優先します。
• 決定的なツール契約とワークフロー動作には 統合 テストを使用します。
• 純粋なロジックとエッジケースには ユニット テストを使用します。
• マージゲートテストでサードパーティの稼働時間に依存しないようにします。統合/ユニット層では外部依存関係をモックします。

デプロイ

Vercelはリポジトリのブランチ設定からリモートサーバーを自動的にデプロイします。プルリクエスト用のプレビュー環境が利用可能です。