pgops-mcp

本番環境向けのMCPサーバー。AIエージェントに、実際のPostgreSQLデータベースとその周辺のDockerスタックに対する、安全で監査可能なエキスパートレベルの制御を提供します。シェルコマンドもPythonスクリプトも不要で、ツールだけです。

なぜ

既存のPostgres MCPサーバーは、単純なクエリラッパーです。スキーマの調査とSELECTのみ。ロック影響分析を伴うマイグレーションを処理するものはなく、EXPLAINとpg_stat_statementsからパフォーマンスを診断するものもなく、データベースが置かれているコンテナ化された環境を理解するものもありません。今日、データベースを操作するエージェントは、目が見えず安全でない状態で飛んでいます。

pgops-mcpは運用の頭脳です。スキーマインテリジェンス → ガード付きクエリ → マイグレーションエンジン → パフォーマンス診断 → 環境認識、そしてすべてのアクションを分類可能・確認可能・監査可能にする安全アーキテクチャを備えています。

Related MCP server: PostgreSQL MCP Server

ツールサーフェス (v0.1)

* サーバーが--approval-modeで実行されない限り、これらは一切登録されません。さらに、各呼び出しには確認トークンが必要です。container.execはさらに、読み取り専用の診断コマンドの許可リストを強制します。シェルは提供されません。Dockerソケットはホスト上でrootと同等の権限を持つため、デフォルトは読み取り専用アクセスです。

安全モデル (中核となる差別化要因)

• 読み取り専用/読み書き用の接続ロールを分離。ツールは適切なロールにバインド

• 実行前のステートメント分類 — 無制限のDELETE/UPDATEはブロック

• 破壊的なアクションには明示的な確認トークンが必要

• 実行されたすべてのステートメントは、タイミングと判定とともに追記専用の監査ログに記録

• タイムアウト階層による暴走クエリのキャンセル

MCPサーフェス

リモートアクセスとエージェントトークン

stdioは認証を必要としません。サーバーはクライアントが起動するサブプロセスであり、開かれたポートはありません。HTTPは認証が必要なため、キーなしでは起動を拒否します。

pgops-mcp keygen                                    # RS256 keypair
pgops-mcp issue-token --subject my-agent            # read-only by default
pgops-mcp issue-token --subject deploy-bot --scope pgops:read --scope pgops:write
pgops-mcp scopes                                    # which scope each tool needs

pgops-mcp --transport http --public-key ~/.pgops/keys/pgops_public.pem

サーバーは公開キーのみを保持するため、トークンを検証できますが、発行はできません。スコープ (pgops:read / pgops:write / pgops:admin) はガードレールと同じ危険度レベルに対応し、スコープエントリのないツールはadminを要求します — デフォルトで拒否。特に指定がない限り、ループバックにバインドします。

クイックスタート

uv sync
# point at your local Postgres in Docker:
export PGOPS_DSN="postgresql://user:pass@localhost:5432/mydb"
uv run pgops-mcp            # stdio transport for Claude Desktop / Cursor / VS Code

Claude Desktopに追加:

{
  "mcpServers": {
    "pgops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pgops-mcp", "pgops-mcp"]
    }
  }
}

ドキュメント

• docs/PRD.md — 何と理由、目標、非目標

• docs/SPEC.md — ハードゲート付きの段階的技術仕様

• docs/ARCHITECTURE.md — システム設計 + トレードオフ

• docs/TOOLS.md — スキーマと例を含む完全なツールカタログ

• docs/adr/ — アーキテクチャ決定記録

• docs/flow.md — 進行中の進捗ログ

• docs/interview_prep.md — 増え続けるインタビューQ&A

ステータス

フェーズ0〜6b完了 (319テスト、すべてのガードレール、判定、ロック影響ルールが、モックなしでtestcontainersを介した実際のPostgresに対して証明済み。さらに、サーバーを実際のMCPサブプロセスとしてstdio経由で、また認証付きHTTPサーバーとして駆動するエンドツーエンドスイートも含む)。

migration.rollbackは意図的にまだ未実装です — docs/TOOLS.mdを参照してください。

120万行のordersに対する型変更でmigration.planが返すサンプル:

ALTER TABLE "orders" ALTER COLUMN "total_cents" TYPE bigint
  op=table_rewrite  risk=high  estimate=4800ms  confidence=medium
  why:   rewrites every row and rebuilds every index, holding AccessExclusiveLock
  SAFER: add a new column of the target type, backfill in batches, sync with a
         trigger, swap the names, then drop the old column

開発データベースをクイックスタート (ホストポート5433、ローカルのPostgres (5432) との衝突を回避):

docker compose up -d
export PGOPS_DSN="postgresql://pgops:pgops_dev@localhost:5433/pgops_demo"
uv run pgops-mcp --selfcheck