pgmcp

pgmcp

pgmcp は、公式の modelcontextprotocol/go-sdk を基盤に構築された、Model Context Protocol 用の読み取り専用 PostgreSQL 運用／DBA サーバーです。インシデント発生時に DBA が尋ねる質問に答えます。どのステートメントが遅いのか、このプランが遅い理由は何か、不要なインデックスはどれか、オートバキュームが遅れているテーブルはどれか、誰が誰をブロックしているのか、スタンバイの遅延はどれくらいか、といった質問です。また、慣例ではなく設計によって読み取り専用を実現しています。書き込み権限を持たない専用のデータベースロール、各ステートメントを囲む BEGIN READ ONLY トランザクションとステートメントタイムアウト、さらに単一の SELECT／EXPLAIN／SHOW 以外のステートメントや、読み取り専用トランザクション内から状態を変更する可能性のあるすべての関数を拒否する SQL パーサーガードを備えています。PostgreSQL 16 でテスト済みで、13 以降が必要です。

インストール

Claude Desktop、ワンクリック： Releases から pgmcp_<version>.mcpb をダウンロードして開きます。Claude Desktop が Postgres の接続文字列を求め、OS のキーチェーンに保存して、同梱のバイナリを自ら起動します。PATH の設定も、編集が必要な設定ファイルもありません。1 つのバンドルで macOS（ユニバーサル）と Windows（x64）に対応します。

または、Releases からお使いのプラットフォーム用のバイナリをダウンロードしてください。darwin、linux、windows、amd64、arm64 に対応し、チェックサムも用意されています。

または、Go CLI ツールの go を使ってソースからビルドします：

go install github.com/pascalallen/pgmcp/cmd/pgmcp@latest

または、distroless、非 root、マルチアーキテクチャのリリースイメージを実行します：

docker run --rm -i -e PGMCP_DATABASE_URL='postgres://…' ghcr.io/pascalallen/pgmcp

pgmcp は MCP Registry に io.github.pascalallen/pgmcp として登録されています。

接続先として使う前に、読み取り専用ロールを作成してください。データベースロールを参照してください。他の 2 つの層にバグがあった場合でも、これが最後の安全策になります。

使用方法

MCP のインターフェースは 1 つで、トランスポートは 2 種類です。どちらを使うかは設定で決まり、ビルドが異なるわけではありません。

Claude Code、stdio — クライアントがバイナリを起動し、stdin/stdout 経由で通信します：

claude mcp add pgmcp --transport stdio \
  --env PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
  -- pgmcp

Claude Desktop、stdio — Releases から .mcpb バンドルをインストールするか（インストールを参照）、同じ内容を claude_desktop_config.json に手動で記述します：

{
  "mcpServers": {
    "pgmcp": {
      "command": "pgmcp",
      "env": {
        "PGMCP_DATABASE_URL": "postgres://pgmcp:…@db.internal:5432/app?sslmode=require"
      }
    }
  }
}

HTTP — 共有環境でのデプロイ向けに、静的なベアラーキーで保護された Streamable HTTP を使用します。pgmcp はプレーンな HTTP を使用し、自身で TLS を終端することはありません。リバースプロキシの背後でループバック上に実行してください。

PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
PGMCP_AUTH_MODE=static \
PGMCP_API_KEYS="$(openssl rand -hex 32)" \
  pgmcp --transport http --listen 127.0.0.1:8080

claude mcp add pgmcp --transport http https://pgmcp.example.com/mcp \
  --header "Authorization: Bearer <key>"

TLS 終端、ストリーミングトランスポートに必要なプロキシ設定、ID プロバイダーを使った JWT 認証、pgmcp を claude.ai のカスタムコネクターとして接続する方法については、docs/DEPLOYING.mdを参照してください。

ツール

ツール	回答する質問
top_queries	サーバー全体で、遅い、またはコストの高いステートメントはどれですか？pg_stat_statements を合計時間、平均時間、呼び出し回数、行数、または読み取りブロック数でランク付けします。
explain	このステートメントが遅いのはなぜですか？プランツリー、自己処理時間を最も消費しているノード、プランの警告、後続の実行結果と比較するための安定した plan_hash を示します。
index_health	削除できるインデックスと、役割を果たせていないインデックスはどれですか？一度もスキャンされていないインデックス、重複したインデックス、無効なインデックス、肥大化したインデックスを示します。
table_health	autovacuum が遅れているのはどこですか？テーブルごとのデッドタプル比率、最終 vacuum／analyze の実行時刻、シーケンシャルスキャンとインデックススキャンの比率、推定肥大化量を示します。
lock_waits	このクエリが停止しているのはなぜですか？現在のロック待機グラフを示します。ブロックされている対象、それをブロックしている対象、デッドロックに相当する循環があればそれも示します。
connections	サーバーは現在何をしていて、max_connections にどれくらい近づいていますか？アイドル・イン・トランザクションのセッションを含め、バックエンドを状態、待機イベント、アプリケーション、ユーザー、またはデータベースごとにグループ化して示します。
replication	スタンバイはどれくらい遅れていて、どのスロットが WAL を保持していますか？プライマリ／スタンバイのロール、スタンバイごとの遅延（バイト数およびミリ秒）、スロット、現在の WAL レートを示します。
config_check	このサーバーの設定は適切ですか？pg_settings をメモリ、autovacuum、WAL、接続に関するヒューリスティクスと照合し、各設定について ok／review／warn の判定と注記を返します。
query	他の 8 つのツールで対応できないすべての内容です。READ ONLY トランザクション内で、行数の上限とステートメントタイムアウトを設けて、読み取り専用の SELECT／EXPLAIN／SHOW を 1 つ実行します。$1..$n のバインドパラメーターに対応しています。

すべてのツールには readOnlyHint: true、destructiveHint: false、idempotentHint: true、openWorldHint: false の注釈があり、型付きの出力スキーマを返します。

自由形式の SQL を扱うツールは query だけで、これはオプションです。--disable-query を指定すると、ツールカタログから完全に除外されます。8 つの診断ツールだけが必要なデプロイでは、アドホックな SQL の実行機能を一切公開せずに運用できます。--query-schemas=public,app を指定すると、対象を指定したスキーマに制限できます。また、analyze=true はステートメントを実行するため、explain の対象も制限されます。この設定で防げることと防げないことについては、docs/SECURITY.md をお読みください。

リソースとプロンプト

リソース	内容
pgmcp://overview	最初に確認するサーバーのスナップショットです。バージョン、稼働時間、リカバリ状態、インストール済みの拡張機能、データベースごとのサイズ、キャッシュヒット率、max_connections に対する接続数を示します。30 秒間キャッシュ可能です。
pgmcp://settings	pg_settings の生の行データです。5 分間キャッシュ可能です。

プロンプト	引数	目的
diagnose_slow_query	sql（必須）	4 段階の調査を行います。ステートメントを explain し、プランのホットノードにあるすべてのスキーマについて index_health／table_health を確認し、top_queries で検索したうえで、根本原因、根拠、推奨するインデックスまたは書き換えをまとめます。結果はテキストとしてのみ出力し、実行はしません。

設定

すべての設定には --flag と環境変数 PGMCP_<KEY> があります。フラグは環境変数より優先され、環境変数はデフォルト値より優先されます。設定エラーの場合は、該当するすべてのキーを1つのメッセージに表示して終了コード 2 で終了します。実行時エラーの場合は、終了コード 1 で終了します。

フラグ	環境変数	デフォルト	意味
--database-url	PGMCP_DATABASE_URL	— (必須)	Postgres の接続文字列
--transport	PGMCP_TRANSPORT	stdio	stdio または http
--listen	PGMCP_LISTEN	127.0.0.1:8080	HTTP のリッスンアドレス
--resource-url	PGMCP_RESOURCE_URL	—	OAuth リソースメタデータ用の、このサーバーにアクセスできるパブリックオリジン
--auth-mode	PGMCP_AUTH_MODE	none	none、static、または jwt（HTTP のみ）
--api-keys	PGMCP_API_KEYS	—	カンマ区切りの静的 API キー。static では必須
--jwks-url	PGMCP_JWKS_URL	—	JWK セットの URL。jwt では必須
--jwt-issuer	PGMCP_JWT_ISSUER	—	必須の iss クレーム。jwt では必須
--jwt-audience	PGMCP_JWT_AUDIENCE	—	必須の aud クレーム。jwt では必須
--auth-servers	PGMCP_AUTH_SERVERS	—	RFC 9728 で通知する OAuth 認可サーバーのカンマ区切りリスト
--disable-query	PGMCP_DISABLE_QUERY	false	アドホックな query ツールを完全に無効にします
--query-schemas	PGMCP_QUERY_SCHEMAS	—	query ツールと explain ツールによる読み取りを許可するスキーマのカンマ区切りリスト。未設定の場合、許可リストは無効になります
--max-conns	PGMCP_MAX_CONNS	4	Postgres の最大接続数
--call-timeout	PGMCP_CALL_TIMEOUT	60s	ツール呼び出しごとのタイムアウト
--rate-limit	PGMCP_RATE_LIMIT	60	プリンシパルごとの1分あたりのツール呼び出し数（HTTP のみ）
--max-output-bytes	PGMCP_MAX_OUTPUT_BYTES	1048576	ツール呼び出しの構造化コンテンツの上限
--log-level	PGMCP_LOG_LEVEL	info	debug、info、warn、または error
--log-format	PGMCP_LOG_FORMAT	text	text または json
--insecure-no-auth	PGMCP_INSECURE_NO_AUTH	false	ループバック以外のリッスンアドレスで auth-mode=none を許可します
--version	—	—	バージョンを表示して終了します

認証設定は HTTP トランスポートにのみ適用されます。stdio では、呼び出し元を判断するのはオペレーティングシステムです。呼び出し元はバイナリを起動した親プロセスであり、それ以外はありません。

セキュリティモデル

• 3つの独立した方法で読み取り専用にします。 書き込み権限を持たない専用ロール（pg_monitor と SELECT を付与し、意図的に pg_signal_backend は付与しません）、アダプターが実行する各ステートメントの前後を BEGIN READ ONLY、SET LOCAL statement_timeout、lock_timeout = '2s' で囲み、必ずロールバックする方法、そしてパーサーレベルのガードです。読み取り専用トランザクションだけでは pg_terminate_backend、pg_read_file、pg_sleep、setval を防げないためです。
• SQL ガードは許可リストを優先します。 トップレベルのステートメントは1つだけで、SELECT、EXPLAIN、SHOW のいずれかでなければなりません。構文木のどこにもネストされた書き込みステートメントがあってはならず、FOR UPDATE／FOR SHARE によるロック句や SELECT INTO も禁止です。また、ファイルアクセス、バックアップおよび WAL の制御、レプリケーションスロット、アドバイザリロック、dblink、シーケンスの変更、統計情報のリセットに関する禁止関数を呼び出すこともできません。
• スキーマの許可リストはガードレールであり、境界ではありません。 --query-schemas は、解析済みステートメント内の テーブル参照 に付くスキーマ名と大文字小文字を区別せず照合します。また、呼び出し元が指定した SQL を受け取る query と explain の両ツールを制限するため、analyze=true を指定した explain でも、除外したスキーマに対して実行することはできません。ただし、許可されたスキーマ内のビュー、集合を返す関数、SECURITY DEFINER 関数から、許可リスト外を読み取ることは可能です。境界となるのはデータベース権限であり、許可リストは明白な経路を狭めるものです。
• 認証を必須とし、フェイルクローズで、HTTP 経由で提供します。 静的キーは、早期終了せず、保存されているすべてのハッシュと定時間で比較します。JWT は非対称アルゴリズムのみを使用して JWK セットに照らして検証され（alg=none や HMAC の混同は許可しません）、iss、aud、exp が必須です。また、検証器は JWKS を受信するまでキーを保持しないため、オープンではなくクローズの状態で起動します。RFC 9728 の保護対象リソースメタデータに、トークンの取得先を示します。認証を無効にしたままループバック以外のアドレスで起動することはできません。
• 各種上限を設けています。 プリンシパルごとのレート制限、呼び出しごとのタイムアウト、トランザクション内のステートメントタイムアウトとロックタイムアウト、query ツールの行数上限、結果の構造化コンテンツのサイズ上限、リクエスト本文の1 MiB上限があります。
• 機密情報は一切ログに記録しません。 ツール呼び出しでは、名前、所要時間、結果、呼び出し元のユーザー ID のみを記録し、引数、SQL テキスト、結果の行、エラーテキストは記録しません。解析エラーにはステートメントをそのまま返さず、固定の文言を返します。また、接続エラーに含まれる DSN は伏せられます。

脅威モデル、各レイヤーの詳細な説明、およびそれぞれがカバーしない制限事項については、docs/SECURITY.md を参照してください。

テスト

レース検出器とカバレッジを有効にしてテストスイートを実行します。

go test -race -cover ./...

統合テストには Postgres データベースが必要で、PGMCP_TEST_DSN が設定されていない場合はスキップされます。pg_stat_statements を事前に読み込んだ一時的な Postgres に対して実行するには、次のようにします。

docker run -d --rm --name pg -e POSTGRES_PASSWORD=postgres -p 5544:5432 postgres:16 \
  -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all
docker exec pg psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements"
PGMCP_TEST_DSN="postgres://postgres:postgres@localhost:5544/postgres?sslmode=disable" go test -race -cover ./...

カバレッジプロファイルを作成して表示します。

go test -covermode=count -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

公式 MCP 適合性テストスイートを使って実行中のサーバーをテストするか、Inspector でスモークテストを行います。

npx -y @modelcontextprotocol/conformance server --url http://127.0.0.1:8080/mcp \
  --expected-failures .github/conformance-expected-failures.yaml
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http --method tools/list

コントリビューション

プルリクエストを歓迎します。大規模な変更の場合は、変更内容を議論するため、まず issue を作成してください。

必要に応じてテストも更新してください。

ライセンス

MIT