Neon MCP Server

公式

Interact with the Neon serverless Postgres platform

ドキュメント

Neon MCP Server

Neon MCP Server は、自然言語で Neon Postgres データベースとやり取りできるオープンソースツールです。

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

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

Neon MCP Server の主な機能は次のとおりです。

自然言語による対話: 直感的で会話的なコマンドを使用して 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 Server のセキュリティに関する考慮事項
Neon MCP Server は、自然言語による要求を通じて強力なデータベース管理機能を提供します。LLM によって要求されたアクションは、実行前に必ず確認して承認してください。 許可されたユーザーとアプリケーションのみが Neon MCP Server にアクセスできるようにしてください。

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

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

Neon MCP Server のセットアップ

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

API キーを使用したクイックセットアップ (Cursor、VS Code、Claude Code): neonctl@latest init を実行して、Neon の MCP Server、エージェントスキル、および VS Code 拡張機能を 1 つのコマンドで自動設定します。
リモート MCP Server (OAuth ベースの認証): OAuth を使用して認証を行い、Neon のマネージド MCP サーバーに接続します。この方法は、API キーを管理する必要がなくなるため、より便利です。さらに、最新の機能と改善点がリリースされ次第、自動的に利用できるようになります。
リモート MCP Server (API キーベースの認証): API キーを使用して認証を行い、Neon のマネージド MCP サーバーに接続します。この方法は、OAuth が利用できないリモートエージェントを Neon に接続する場合に役立ちます。さらに、最新の機能と改善点がリリースされ次第、自動的に利用できるようになります。

前提条件

MCP クライアントアプリケーション。
Neon アカウント。
Node.js (>= v18.0.0): nodejs.org からダウンロードしてください。

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

オプション 1. API キーを使用したクイックセットアップ

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

neonctl@latest init を実行して、Neon の MCP Server を 1 つのコマンドで自動設定します。

npx neonctl@latest init

これは Cursor、VS Code (GitHub Copilot)、Claude Code で動作します。OAuth 経由で認証し、Neon API キーを作成し、エディターを自動的に設定します。

オプション 2. リモートホスト MCP Server (OAuth ベースの認証)

OAuth を使用して認証を行い、Neon のマネージド MCP サーバーに接続します。これが最も簡単なセットアップであり、このサーバーのローカルインストールは不要で、クライアントで Neon API キーを設定する必要もありません。

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

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

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

または、クライアントの 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 Server (API キーベースの認証)

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

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

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 つの方法で設定できます。

OAuth スコープの選択 (推奨): OAuth で、認証 UI の フルアクセス のチェックを外して読み取り専用を選択します。
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
search、fetch、list_docs_resources、get_doc_resource

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

create_project、delete_project
create_branch、delete_branch、reset_from_parent
provision_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 Server を追加します。

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

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

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

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

コア実装領域:

landing/app/api/[transport]/route.ts: Streamable HTTP (/mcp) および SSE (/sse) 用の MCP トランスポートエンドポイント
landing/app/api/authorize/、landing/app/callback/、landing/app/api/token/、landing/app/api/revoke/: OAuth フローエンドポイント
landing/app/.well-known/: OAuth 検出メタデータエンドポイント
landing/mcp-src/: MCP サーバー、ツール、ハンドラー、分析、Sentry 統合
landing/lib/: Next.js 互換ヘルパー (OAuth、設定、エラー処理)
landing/mcp-src/utils/read-only.ts: 読み取り専用モードとスコープ処理

ガイド

機能

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

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

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

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

projects
branches
schema
querying
neon_auth
data_api
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: 現在のユーザーがアクセスできるすべての組織を一覧表示します。必要に応じて、検索パラメータを使用して組織名またはIDでフィルタリングします。

ブランチ管理:

create_branch: 指定されたNeonプロジェクト内に新しいブランチを作成します。Neonのブランチ機能を活用して、開発、テスト、または移行を行います。
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 Auth:

provision_neon_auth: NeonプロジェクトにNeon Authをプロビジョニングします。開発者は、認証プロバイダーとの統合を作成することで、認証インフラストラクチャを簡単にセットアップできます。

Neon Data API:

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

検索と検出:

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

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

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は「開始」（prepare_database_migration）と「コミット」（complete_database_migration）の個別のコマンドで安全に移行を実行できます。

「開始」コマンドは移行を受け入れ、新しい一時ブランチで実行します。戻り時に、このコマンドはLLMに対して、このブランチで移行をテストする必要があることを示唆します。その後、LLMは「コミット」コマンドを実行して、元のブランチに移行を適用できます。

開発

このプロジェクトは、Corepackを介して固定されたパッケージマネージャーとしてpnpmを使用します。

プロジェクト構造

MCPサーバーコードは landing/ ディレクトリにあり、これは mcp.neon.tech のVercelにデプロイされるNext.jsアプリケーションです。

cd landing
corepack enable
pnpm install

ローカル開発

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

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

pnpm run lint
pnpm run 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`

テストピラミッド

すべてのテストは landing/ から実行されます。

cd landing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

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

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

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

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

テスト戦略:

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

デプロイ

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