pgcloud

pgcloud

pgcloud を使用すると、MCP クライアントまたはターミナルから Neon Postgres アカウントを利用できます。プロジェクトとそのブランチの一覧表示、詳細表示、作成、削除ができ、コンピュートエンドポイントと組織を確認できるほか、プロジェクト内の任意のデータベースに直接クエリを実行できます。単一ステートメント、複数ステートメントのトランザクション、テーブルとカラムのイントロスペクション、低速クエリレポート、実行計画に対応しています。スキーマの変更は、Neon の 2 フェーズ方式に従います。移行またはチューニングセッションを一時ブランチで準備して実行し、その後に元のブランチへ反映します。

Neon API キーが必要です。NEON_API_KEY 環境変数に設定してください。このキーは Bearer トークンとして Neon API に送信され、出力に表示されることはありません。変数が設定されていない場合、すべての呼び出しは変数名を示すエラーで失敗します。

インストール

npx @reneturcios/pgcloud list_projects

または、コンテナイメージを実行します。

docker run -i -e NEON_API_KEY ghcr.io/cloudcorprecords/pgcloud

コンテナはデフォルトで MCP サーバーとして動作します（下記を参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

すべての MCP ツールは CLI サブコマンドとしても使用できます。ツールの引数は --json を使って単一の JSON オブジェクトとして渡します。

export NEON_API_KEY=<your Neon API key>

pgcloud list_projects
pgcloud list_projects --json '{"limit": 5, "search": "billing"}'
pgcloud describe_project --json '{"projectId": "snowy-pond-12345678"}'
pgcloud create_branch --json '{"projectId": "snowy-pond-12345678", "branchName": "dev"}'
pgcloud run_sql --json '{"projectId": "snowy-pond-12345678", "sql": "select now()"}'
pgcloud get_connection_string --json '{"projectId": "snowy-pond-12345678", "pooled": true}'

pgcloud --version

結果は JSON として出力されます。終了コード：成功時は 0、API または SQL 呼び出しの失敗時（NEON_API_KEY が未設定の場合を含む）は 1、使用法エラーの場合は 2 です。

MCP サーバー

1 つのバイナリで両方のインターフェースを提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/pgcloud mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "pgcloud": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pgcloud", "mcp"],
      "env": { "NEON_API_KEY": "your Neon API key" }
    }
  }
}

ツール

ツール	入力（太字は必須）	説明
list_projects	limit、search、org_id	アカウント内のプロジェクトを一覧表示します。
describe_project	projectId	1 つのプロジェクトの詳細を表示します。
create_project	name、region_id、org_id	プロジェクトを作成します。
delete_project	projectId	プロジェクトとそのリソースを削除します。
create_branch	projectId、branchName、parentBranchId	読み書き可能なコンピュートを備えたブランチを作成します。
delete_branch	projectId、branchId	ブランチを削除します。
describe_branch	projectId、branchId	ブランチのレコードとそのデータベースを表示します。
list_branch_computes	projectId、branchId	コンピュートエンドポイントを一覧表示します。
list_organizations	search	ユーザーがアクセスできる組織を一覧表示します。
get_connection_string	projectId、branchId、databaseName、roleName、pooled	Postgres 接続文字列を解決します。
run_sql	sql、projectId、branchId、databaseName、roleName	SQL ステートメントを 1 つ実行します。
run_sql_transaction	sql（配列）、projectId、…	1 つのトランザクション内でステートメントを実行します。
get_database_tables	projectId、branchId、databaseName	information_schema を通じてテーブルを一覧表示します。
describe_table_schema	projectId、tableName、…	テーブルのカラムを一覧表示します。
list_slow_queries	projectId、limit、…	pg_stat_statements から低速なクエリを取得します。
explain_sql_statement	sql、projectId、…	ステートメントの EXPLAIN 計画を返します。
prepare_database_migration	migrationSql、projectId、…	一時ブランチで移行 SQL を実行します。
complete_database_migration	migrationId、projectId、…	準備済みの移行を元のブランチに適用します。
prepare_query_tuning	sql、projectId、…	計画とともに一時ブランチでチューニングセッションを開始します。
complete_query_tuning	tuningId、projectId、applyChanges	チューニングセッションを終了し、変更を適用するか破棄します。

管理呼び出しは https://api.neon.tech/api/v2 に送信されます。SQL 呼び出しでは、まず API からブランチの接続 URI を解決し、次に URI を Neon-Connection-String ヘッダーに含めて、データベースホストの HTTP SQL エンドポイントへステートメントを POST します。SQL テキストはそのまま渡されます。移行セッションとチューニングセッションはサーバープロセス内に保持されるため、準備したプロセスと同じプロセスで完了する必要があります。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。