postgres-scout-mcp

Postgres Scout MCP

AI で PostgreSQL データベースを調査しましょう。安全機能、モニタリング、データ品質ツールを内蔵した、本番環境対応の Model Context Protocol サーバーです。

得られるもの

次のように尋ねます。

「本番データベースの健全性はどうですか？ 緊急の問題はありますか？」

Postgres Scout は次の結果を返します。

全体の健全性スコア：78/100

コンポーネント別の内訳

検出された問題

• 高 — テーブル orders は34%肥大化しています（2.1 GB の無駄）。VACUUM FULL を推奨します。
• 中 — sessions に未使用のインデックスが3つあり、890 MB を消費しています。
• 低 — analytics_events のキャッシュヒット率は71%です（目標：>90%）。

推奨事項

• メンテナンス時間中に VACUUM FULL orders を実行してください
• 未使用のインデックスを削除してください：idx_sessions_legacy、idx_sessions_old_token、idx_sessions_temp
• analytics_events を shared_buffers に追加するか、日付ごとにパーティション分割することを検討してください

これが getHealthScore です。データベースの調査、診断、最適化、モニタリング、データ品質、安全な書き込みをカバーする38個のツールのうちの1つです。

クイックスタート

Claude Code

claude mcp add postgres-scout -- npx -y postgres-scout-mcp postgresql://localhost:5432/mydb

次に、*「サイズが最も大きいテーブルと、肥大化の問題があるかどうかを表示してください」*と尋ねてください。

{
  "mcpServers": {
    "postgres-scout": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"],
      "type": "stdio"
    }
  }
}

{
  "postgres-scout": {
    "command": "npx",
    "args": ["-y", "postgres-scout-mcp", "postgresql://localhost:5432/mydb"]
  }
}

{
  "mcpServers": {
    "postgres-scout-readonly": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "--read-only", "postgresql://localhost:5432/production"],
      "type": "stdio"
    },
    "postgres-scout-readwrite": {
      "command": "npx",
      "args": ["-y", "postgres-scout-mcp", "--read-write", "postgresql://localhost:5432/development"],
      "type": "stdio"
    }
  }
}

ツール

調査 — データベースを把握する

• listDatabases — ユーザーがアクセスできるデータベース
• getDatabaseStats — サイズ、キャッシュヒット率、接続情報
• listSchemas — 現在のデータベース内のすべてのスキーマ
• listTables — サイズと行の統計情報を含むテーブル
• describeTable — カラム、制約、インデックスなど

クエリ — 実行と分析

• executeQuery — SELECT クエリを実行します（読み書きモードでは書き込みも可能）
• explainQuery — パフォーマンス分析用の EXPLAIN プラン
• optimizeQuery — 特定のクエリに対する最適化の推奨事項

診断 — 問題が発生する前に検出する

• getHealthScore — コンポーネント別の内訳を含む全体の健全性スコア
• detectAnomalies — パフォーマンス、接続、データの異常
• analyzeTableBloat — VACUUM の計画に役立つ肥大化分析
• getSlowQueries — 遅いクエリの分析（pg_stat_statements が必要です）
• suggestVacuum — デッドタプルと肥大化に基づく VACUUM の推奨事項

最適化 — 高速化する

• suggestIndexes — クエリパターンに基づく不足インデックスの推奨事項
• suggestPartitioning — 大きなテーブルのパーティション分割戦略
• getIndexUsage — 未使用または使用頻度の低いインデックスを特定します

モニタリング — リアルタイムで監視する

• getCurrentActivity — 実行中のクエリと接続
• analyzeLocks — ロックの競合とブロックしているクエリ
• getLiveMetrics — 指定した時間範囲のリアルタイムメトリクス
• getHottestTables — アクティビティが最も多いテーブル
• getTableMetrics — テーブルごとの I/O とスキャン統計の包括的な情報

データ品質 — データの信頼性を高める

• findDuplicates — カラムの組み合わせに基づく重複行
• findMissingValues — カラム全体の NULL 分析
• findOrphans — 無効な外部キーを持つ孤立レコード
• checkConstraintViolations — 制約を追加する前に違反がないか確認します
• analyzeTypeConsistency — テキストカラム内の型の不整合

リレーションシップ — 接続をたどる

• exploreRelationships — 外部キーを複数段階でたどります
• analyzeForeignKeys — 外部キーの健全性とパフォーマンスを分析します

時系列 — 時間軸に沿った分析

• findRecent — 指定した時間範囲内の行を検索します
• analyzeTimeSeries — ウィンドウ関数と異常検出
• detectSeasonality — 季節パターンを検出します

エクスポート — データを取り出す

• exportTable — CSV、JSON、JSONL、または SQL
• generateInsertStatements — 移行用の INSERT ステートメント

書き込み（読み書きモードのみ） — 安全な変更

• previewUpdate / previewDelete — コミット前に変更内容を確認します
• safeUpdate — ドライラン、行数制限、空の WHERE 句の保護を備えた UPDATE
• safeDelete — ドライラン、行数制限、空の WHERE 句の保護を備えた DELETE
• safeInsert — 検証、バッチ処理、ON CONFLICT 対応を備えた INSERT

セキュリティ

• デフォルトは読み取り専用 — 書き込み操作は明示的に有効にする必要があります
• すべてのクエリでパラメーター化された値を使用します
• 入力検証とパターン検出により SQL インジェクションを防止します
• テーブル名／列名をサニタイズします
• すべての操作にレート制限を適用します
• 長時間実行されるクエリを防ぐため、クエリにタイムアウトを設定します
• メモリ枯渇を防ぐため、レスポンスサイズを制限します

使用例

「最も大きなテーブルはどれですか？肥大化していますか？」

listTables({ schema: "public" })
analyzeTableBloat({ schema: "public", minSizeMb: 100 })

「users テーブル内の重複したメールアドレスを見つけてください。」

findDuplicates({ table: "users", columns: ["email"] })

「最も遅いクエリはどれですか？高速化するにはどうすればよいですか？」

getSlowQueries({ minDurationMs: 100, limit: 10 })
suggestIndexes({ schema: "public" })

「現在、データベースで何が起きているかを表示してください。」

getCurrentActivity()
getLiveMetrics({ metrics: ["queries", "connections", "cache"], duration: 30000, interval: 1000 })
getHottestTables({ limit: 5, orderBy: "seq_scan" })

「削除された顧客を参照している孤立した注文を見つけてください。」

findOrphans({ table: "orders", foreignKey: "customer_id", referenceTable: "customers", referenceColumn: "id" })

設定

CLI フラグ：--read-only（デフォルト）、--read-write、--mode <mode>

ログ記録

ファイルへのログ記録はデフォルトで無効です。有効にするには、ENABLE_LOGGING=true を設定してください。LOG_DIR に次の 2 つのログファイルが作成されます。

• tool-usage.log — タイムスタンプ、名前、引数を含むすべてのツール呼び出し
• error.log — スタックトレースを含むエラー

すべての出力で接続文字列は自動的にマスキングされます。

開発

git clone https://github.com/bluwork/postgres-scout-mcp.git
cd postgres-scout-mcp
pnpm install
pnpm build
pnpm test

ライセンス

Apache-2.0