mcp-percona-pg

mcp-percona-pg

Percona Operator for PostgreSQL 向けの Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、…）から、Kubernetes 上の PostgreSQL + PgBouncer クラスターを操作できます。トポロジー、コネクションプーリング、チューニング、バックアップ／PITR、DR、拡張機能、ライフサイクルをすべてフラグで制御できます。

kube-config を介してオペレーターのカスタムリソース（PerconaPGCluster、PerconaPGBackup、PerconaPGRestore、PerconaPGUpgrade）を操作するため、モデルは普段の操作方法に合わせて動作します。「dev-pg を 3 レプリカにスケールする」、「プーリングをトランザクションモードに切り替える」、*「prod-pg を 12:00 UTC 時点に復元する」*といった指示が可能です。

デフォルトで安全です。起動時は読み取り専用で、許可リストで名前空間とクラスターを限定でき、重要なクラスターへの変更を防ぎ、復元／アップグレード／削除はそれぞれ別途オプトインが必要です。また、影響の大きい操作には、指定された確認入力を求めます。データベースの認証情報を読み取ったり返したりすることはありません。

機能

• 検出とステータス — クラスター一覧、クラスターごとの概要と未加工の .status（Patroni メンバー、PostgreSQL／PgBouncer の準備状況）、接続エンドポイント、バックアップと復元を確認できます。
• コネクションプーリング — PgBouncer の pool_mode と、グローバルなプール調整値（default_pool_size、max_client_conn、…）を読み取り、更新できます。
• PostgreSQL のチューニング — spec.patroni.dynamicConfiguration を介してパラメーターを読み取り／マージします（Patroni で安全に設定できる唯一の方法です）。
• ライフサイクル — PostgreSQL／PgBouncer のスケール、停止／再開、組み込み拡張機能の切り替え、オンデマンドバックアップに対応します。
• DR と復旧 — 復元／ポイントインタイムリカバリ、スタンバイの昇格、メジャーバージョンアップグレードに対応します。各機能は個別に有効化が必要です。

セキュリティモデル

レイヤー	フラグ	効果
アクセスモード	PERCONA_MODE	read-only → read-write → admin。権限が不足するツールは登録されません
名前空間／クラスターの許可リスト	PERCONA_NAMESPACE_ALLOWLIST、PERCONA_CLUSTER_ALLOWLIST	エージェントが操作できる対象を限定します
保護対象クラスター	PERCONA_PROTECTED_CLUSTERS	読み取りは可能ですが、変更／復元／削除はできません
復元／アップグレード／削除	PERCONA_ALLOW_RESTORE、PERCONA_ALLOW_UPGRADE、PERCONA_ALLOW_DELETE	admin モードに加えて、個別にオプトインが必要です
確認	PERCONA_REQUIRE_CONFIRMATION	影響の大きい操作では、クラスター名の再入力が必要です
ドライラン／監査	PERCONA_DRY_RUN、PERCONA_AUDIT_LOG	検証のみを実行します。保護対象の操作ごとに JSON 形式の監査ログを記録します
対話型の確認	(自動)	破壊的な操作や影響の大きい操作では、実行前に MCP elicitation を通じて人間の承認を求めます。クライアントが elicitation に対応していない場合は、PERCONA_ALLOW_* ゲートにフォールバックします

ツール

読み取り（read-only+）：list_contexts、list_clusters、get_cluster、get_cluster_status、get_connection_info、get_pgbouncer_config、get_pg_parameters、list_backups、list_restores

書き込み（read-write+）：scale_cluster、set_pgbouncer_config、set_pg_parameters、pause_cluster、toggle_builtin_extension、create_backup

管理者（admin）：restore_cluster（PERCONA_ALLOW_RESTORE が必要）、upgrade_cluster（PERCONA_ALLOW_UPGRADE が必要）、promote_standby、delete_backup／delete_cluster（PERCONA_ALLOW_DELETE が必要）

クイックスタート — エージェントに追加する

npm で @dockndevai/mcp-percona-pg として公開されています。クローンやビルドは不要です。MCP クライアントが必要に応じて npx で実行します。まずは read-only モードで開始してください。すべての変数については .env.example を、クライアントごとの詳しいガイドについては docs/CLIENTS.md をご覧ください。

Claude Code（CLI）

claude mcp add percona-pg -e PERCONA_MODE="read-only" -e PERCONA_NAMESPACE="postgres-operator" -- npx -y @dockndevai/mcp-percona-pg

Claude Desktop · Cursor · Windsurf — claude_desktop_config.json、.cursor/mcp.json、または ~/.codeium/windsurf/mcp_config.json に同じブロックを指定します。

{
  "mcpServers": {
    "percona-pg": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-percona-pg"],
      "env": {
        "PERCONA_MODE": "read-only",
        "PERCONA_NAMESPACE": "postgres-operator"
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml に指定します。

[mcp_servers.percona-pg]
command = "npx"
args = ["-y", "@dockndevai/mcp-percona-pg"]
env = { PERCONA_MODE = "read-only", PERCONA_NAMESPACE = "postgres-operator" }

プロンプトの例

• 「PostgreSQL クラスターを一覧表示して、dev-pg のステータスを教えてください。」
• 「dev-pg はどの pool_mode を使っていますか？ デフォルトのプールサイズはいくつですか？」 → get_pgbouncer_config
• 「dev-pg の PgBouncer を、default_pool_size 25 のトランザクションプーリングに設定してください。」（read-write が必要です）
• 「dev-pg の shared_buffers を 512MB に増やしてください。」（read-write が必要です）
• 「dev-pg の完全バックアップを repo1 に作成してください。」（read-write が必要です）
• 「dev-pg を 2026-08-30 12:00:00+00 の状態に復元してください。」（admin、PERCONA_ALLOW_RESTORE、および確認が必要です）

前提条件

• Percona Operator for PostgreSQL v2（pgv2.percona.com/v2）が稼働している Kubernetes クラスター。
• サーバーが読み取れる kube-config。安全のため、オペレーターの名前空間と、エージェントに表示させる pgv2.percona.com リソースにスコープを限定した ServiceAccount/RBAC を使用してください。

ソースから実行する（開発）

上記の公開パッケージを推奨します。クローンから実行するには、次の手順に従ってください。

npm install
npm run build
node dist/index.js   # with the environment variables set

開発

npm run dev
npm test          # security policy + annotations
npm run typecheck

公開

このサーバーには、公式 MCP レジストリ用の server.json と、npm の所有権検証用の mcpName が含まれています。PUBLISHING.md をご覧ください。

ライセンス

MIT