Pgtuner MCP

🚀 PostgreSQL Performance Tuning MCP

このModel Context Protocol (MCP)サーバーは、AIを搭載したPostgreSQLのパフォーマンスチューニング機能を提供します。このサーバーは、低速クエリの特定、最適なインデックスの推奨、実行プランの分析、およびHypoPGを使用した仮想インデックスのテストを支援します。

🚀 クイックスタート

このセクションでは、PostgreSQL Performance Tuning MCPの基本的な使い方を説明します。サーバーのインストールから設定、実際の使用までの手順を追っていきます。

✨ 主な機能

クエリ分析

• pg_stat_statementsから低速クエリを詳細な統計情報とともに取得します。
• EXPLAINとEXPLAIN ANALYZEを使用してクエリの実行プランを分析します。
• 自動化されたプラン分析によりパフォーマンスのボトルネックを特定します。
• アクティブなクエリを監視し、長時間実行されるトランザクションを検出します。

インデックスチューニング

• クエリワークロード分析に基づくAIによるインデックス推奨を行います。
• HypoPG拡張機能を使用した仮想インデックステスト（ディスク使用量がない）。
• クリーンアップのために未使用および重複するインデックスを見つけます。
• 作成前にインデックスのサイズを推定します。
• 実装する前に提案されたインデックスでクエリプランをテストします。

データベースの健全性

• 複数のチェックによる包括的な健全性スコアリング。
• 接続利用率の監視。
• キャッシュヒット率の分析（バッファおよびインデックス）。
• ロック競合の検出。
• バキュームの健全性とトランザクションIDのラップアラウンドの監視。
• レプリケーション遅延の監視。
• バックグラウンドライターとチェックポイントの分析。

バキューム監視

• 長時間実行されるVACUUMおよびVACUUM FULL操作をリアルタイムで追跡します。
• オートバキュームの進捗状況とパフォーマンスを監視します。
• バキュームが必要なテーブルを特定します。
• 最近のバキュームアクティビティ履歴を表示します。
• オートバキュームの設定の有効性を分析します。

I/Oパフォーマンス分析

• テーブルとインデックス全体のディスク読み書きパターンを分析します。
• I/Oのボトルネックとホットテーブルを特定します。
• バッファキャッシュのヒット率を監視します。
• work_memの問題を示す一時ファイルの使用量を追跡します。
• チェックポイントとバックグラウンドライターのI/Oを分析します。
• PostgreSQL 16以降の拡張されたpg_stat_ioメトリックのサポート。

設定分析

• カテゴリ別にPostgreSQLの設定をレビューします。
• メモリ、チェックポイント、WAL、オートバキューム、および接続設定の推奨事項を取得します。
• 最適でない設定を特定します。

MCPプロンプトとリソース

• 一般的なチューニングワークフローのための事前定義されたプロンプトテンプレート。
• テーブル統計、インデックス情報、および健全性チェックのための動的リソース。
• 包括的なドキュメントリソース。

📦 インストール

標準インストール（Claude DesktopなどのMCPクライアント用）

pip install pgtuner_mcp

またはuvを使用する場合：

uv pip install pgtuner_mcp

手動インストール

git clone https://github.com/isdaniel/pgtuner_mcp.git
cd pgtuner_mcp
pip install -e .

📚 ドキュメント

設定

環境変数

接続文字列の形式: postgresql://user:password@host:port/database

最小限のユーザー権限

このMCPサーバーを実行するには、PostgreSQLユーザーにシステムカタログと拡張機能を照会するための特定の権限が必要です。以下は、さまざまな機能セットに必要な最小限の権限です。

基本権限（コア機能に必要）

-- 専用の監視ユーザーを作成
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- ターゲットデータベースへの接続を許可
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;

-- スキーマの使用を許可
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;
GRANT USAGE ON SCHEMA pg_catalog TO pgtuner_monitor;

-- ユーザーテーブルとインデックスへのSELECT権限を付与（テーブル統計と分析用）
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- システムカタログビューへのアクセスを許可（読み取り専用）
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

拡張機能固有の権限

pgstattuple（ブロート検出用）:

-- 拡張機能を作成（スーパーユーザーまたは適切な権限が必要）
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- pgstattuple関数の実行を許可
GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstatginindex(regclass) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION pgstathashindex(regclass) TO pgtuner_monitor;

-- 代替案: pg_stat_scan_tablesロールを使用（PostgreSQL 14+）
GRANT pg_stat_scan_tables TO pgtuner_monitor;

HypoPG（仮想インデックステスト用）:

-- 拡張機能を作成（スーパーユーザーまたは適切な権限が必要）
CREATE EXTENSION IF NOT EXISTS hypopg;

-- HypoPGビューへのSELECT権限を付与
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;

-- 適切なシグネチャでHypoPG関数の実行を許可
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- 注意: HypoPGの操作はセッションスコープであり、実際のデータベースに影響を与えません

完全なセットアップスクリプト

-- 1. 監視ユーザーを作成
CREATE USER pgtuner_monitor WITH PASSWORD 'secure_password';

-- 2. 接続とスキーマアクセスを許可
GRANT CONNECT ON DATABASE your_database TO pgtuner_monitor;
GRANT USAGE ON SCHEMA public TO pgtuner_monitor;

-- 3. ユーザーテーブルへの読み取りアクセスを許可
GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgtuner_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgtuner_monitor;

-- 4. システム統計アクセスを許可
GRANT pg_read_all_stats TO pgtuner_monitor;  -- PostgreSQL 10+

-- pg_stat_statementsビューへのアクセスを明示的に許可
GRANT SELECT ON pg_stat_statements TO pgtuner_monitor;
GRANT SELECT ON pg_stat_statements_info TO pgtuner_monitor;

-- 5. 拡張機能をインストールしてアクセスを許可（スーパーユーザーとして）
-- pg_stat_statements（必須）
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- pgstattuple（ブロート検出用）
CREATE EXTENSION IF NOT EXISTS pgstattuple;
GRANT pg_stat_scan_tables TO pgtuner_monitor;  -- PostgreSQL 14+
-- または個々の関数を許可:
-- GRANT EXECUTE ON FUNCTION pgstattuple(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstattuple_approx(regclass) TO pgtuner_monitor;
-- GRANT EXECUTE ON FUNCTION pgstatindex(regclass) TO pgtuner_monitor;

-- hypopg（仮想インデックステスト用）
CREATE EXTENSION IF NOT EXISTS hypopg;
GRANT SELECT ON hypopg_list_indexes TO pgtuner_monitor;
GRANT SELECT ON hypopg_hidden_indexes TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_create_index(text) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_drop_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_reset() TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_hide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_unhide_index(oid) TO pgtuner_monitor;
GRANT EXECUTE ON FUNCTION hypopg_relation_size(oid) TO pgtuner_monitor;

-- 6. 権限を確認
SET ROLE pgtuner_monitor;
SELECT * FROM pg_stat_statements LIMIT 1;
SELECT * FROM pg_stat_activity WHERE pid = pg_backend_pid();
SELECT * FROM pgstattuple('pg_class') LIMIT 1;
SELECT * FROM hypopg_list_indexes();
RESET ROLE;

特定のユーザーを監視から除外する

特定のPostgreSQLユーザーをクエリ分析と監視結果から除外することができます。これは、以下のようなユーザーをフィルタリングするのに役立ちます。

• 監視またはレプリケーションユーザー
• システムアカウント
• 内部アプリケーションサービスアカウント

PGTUNER_EXCLUDE_USERIDS環境変数にユーザーOIDのカンマ区切りリストを設定します。

# ユーザーID 16384、16385、および16386を除外
export PGTUNER_EXCLUDE_USERIDS="16384,16385,16386"

特定のPostgreSQLユーザーのOIDを見つけるには：

SELECT usesysid, usename FROM pg_user WHERE usename = 'monitoring_user';

設定すると、以下のクエリがフィルタリングされます。

• pg_stat_activityクエリ（usesysid列でフィルタリング）
• pg_stat_statementsクエリ（userid列でフィルタリング）

これは、get_slow_queries、get_active_queries、analyze_wait_events、check_database_health、およびget_index_recommendationsなどのツールに影響します。

MCPクライアントの設定

cline_mcp_settings.jsonまたはClaude Desktopの設定に追加します。

{
  "mcpServers": {
    "pgtuner_mcp": {
      "command": "python",
      "args": ["-m", "pgtuner_mcp"],
      "env": {
        "DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

またはストリーミング可能なHTTPモード

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

サーバーモード

1. 標準MCPモード（デフォルト）

# デフォルトモード（stdio）
python -m pgtuner_mcp

# 明示的にstdioモードを指定
python -m pgtuner_mcp --mode stdio

2. HTTP SSEモード（レガシーWebアプリケーション用）

SSE（Server-Sent Events）モードは、MCP通信のためのWebベースのトランスポートを提供します。WebアプリケーションやHTTPベースの通信を必要とするクライアントに役立ちます。

# デフォルトのホスト/ポート（0.0.0.0:8080）でSSEサーバーを起動
python -m pgtuner_mcp --mode sse

# カスタムホストとポートを指定
python -m pgtuner_mcp --mode sse --host localhost --port 3000

# デバッグモードを有効にする
python -m pgtuner_mcp --mode sse --debug

SSEエンドポイント:

SSE用のMCPクライアント設定: SSEトランスポートをサポートするMCPクライアント（Claude Desktopやカスタムクライアントなど）の場合：

{
  "mcpServers": {
    "pgtuner_mcp": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

3. ストリーミング可能なHTTPモード（推奨される最新のMCPプロトコル）

ストリーミング可能なHTTPモードは、単一の/mcpエンドポイントで最新のMCP Streamable HTTPプロトコルを実装します。ステートフル（セッションベース）およびステートレスモードの両方をサポートします。

# ステートフルモード（デフォルト）でストリーミング可能なHTTPサーバーを起動
python -m pgtuner_mcp --mode streamable-http

# ステートレスモードで起動（リクエストごとに新しいトランスポートを作成）
python -m pgtuner_mcp --mode streamable-http --stateless

# カスタムホストとポートを指定
python -m pgtuner_mcp --mode streamable-http --host localhost --port 8080

# デバッグモードを有効にする
python -m pgtuner_mcp --mode streamable-http --debug

ステートフルとステートレスの比較:

• ステートフル（デフォルト）: mcp-session-idヘッダーを使用してリクエスト間でセッション状態を維持します。長時間実行されるインタラクションに最適です。
• ステートレス: セッション追跡なしで各リクエストに新しいトランスポートを作成します。サーバーレスデプロイメントや単純なリクエスト/レスポンスパターンに最適です。

エンドポイント: http://{host}:{port}/mcp

利用可能なツール

⚠️ 重要提示

すべてのツールは、ユーザー/アプリケーションのテーブルとインデックスにのみ焦点を当てています。システムカタログテーブル（pg_catalog、information_schema、pg_toast）はすべての分析から自動的に除外されます。

パフォーマンス分析ツール

インデックスチューニングツール

データベース健全性ツール

ブロート検出ツール（pgstattuple）

バキューム監視ツール

ツールのパラメータ

get_slow_queries

• limit: 返す最大クエリ数（デフォルト: 10）
• min_calls: 最小呼び出し回数フィルター（デフォルト: 1）
• min_mean_time_ms: 最小平均（平均）実行時間（ミリ秒）フィルター
• order_by: mean_time、calls、またはrowsでソート

analyze_query

• query (必須): 分析するSQLクエリ
• analyze: EXPLAIN ANALYZEでクエリを実行（デフォルト: true）
• buffers: バッファ統計を含める（デフォルト: true）
• format: 出力形式 - json、text、yaml、xml

get_index_recommendations

• workload_queries: 分析する特定のクエリのオプションのリスト
• max_recommendations: 最大推奨数（デフォルト: 10）
• min_improvement_percent: 最小改善閾値（デフォルト: 10%）
• include_hypothetical_testing: HypoPGでテストする（デフォルト: true）
• target_tables: 特定のテーブルに焦点を当てる

check_database_health

• include_recommendations: 実行可能な推奨事項を含める（デフォルト: true）
• verbose: 詳細な統計を含める（デフォルト: false）

analyze_table_bloat

• table_name: 分析する特定のテーブルの名前（オプション）
• schema_name: スキーマ名（デフォルト: public）
• use_approx: 大規模なテーブルの高速分析にpgstattuple_approxを使用する（デフォルト: false）
• min_table_size_gb: スキーマ全体のスキャンに含める最小テーブルサイズ（GB）（デフォルト: 5）
• include_toast: TOASTテーブルの分析を含める（デフォルト: false）

analyze_index_bloat

• index_name: 分析する特定のインデックスの名前（オプション）
• table_name: このテーブルのすべてのインデックスを分析する（オプション）
• schema_name: スキーマ名（デフォルト: public）
• min_index_size_gb: 含める最小インデックスサイズ（GB）（デフォルト: 5）
• min_bloat_percent: このパーセンテージ以上のブロートのあるインデックスのみを表示する（デフォルト: 20）

get_bloat_summary

• schema_name: 分析するスキーマ（デフォルト: public）
• top_n: 表示する最上位のブロートのあるオブジェクトの数（デフォルト: 10）
• min_size_gb: 含める最小オブジェクトサイズ（GB）（デフォルト: 5）

monitor_vacuum_progress

• action: 実行するアクション - progress（アクティブなバキューム操作を監視）、needs_vacuum（バキュームが必要なテーブルを見つける）、autovacuum_status（オートバキュームの設定をレビュー）、またはrecent_activity（最近のバキューム履歴を表示）
• schema_name: 分析するスキーマ（デフォルト: public、needs_vacuumアクションで使用）
• top_n: 返す結果の数（デフォルト: 20）

analyze_disk_io_patterns

• analysis_type: I/O分析のタイプ - all（包括的）、buffer_pool（キャッシュヒット率）、tables（テーブルI/Oパターン）、indexes（インデックスI/Oパターン）、temp_files（一時ファイルの使用量）、またはcheckpoints（チェックポイントI/O統計）
• schema_name: 分析するスキーマ（デフォルト: public）
• top_n: 表示する最上位のI/O集中型オブジェクトの数（デフォルト: 20）
• min_size_gb: 含める最小オブジェクトサイズ（GB）（デフォルト: 1）

MCPプロンプト

サーバーには、ガイド付きチューニングセッションのための事前定義されたプロンプトテンプレートが含まれています。

MCPリソース

静的リソース

• pgtuner://docs/tools - 完全なツールドキュメント
• pgtuner://docs/workflows - 一般的なチューニングワークフローガイド
• pgtuner://docs/prompts - プロンプトテンプレートのドキュメント

動的リソーステンプレート

• pgtuner://table/{schema}/{table_name}/stats - テーブル統計
• pgtuner://table/{schema}/{table_name}/indexes - テーブルインデックス情報
• pgtuner://query/{query_hash}/stats - クエリパフォーマンス統計
• pgtuner://settings/{category} - PostgreSQLの設定（メモリ、チェックポイント、wal、オートバキューム、接続、すべて）
• pgtuner://health/{check_type} - 健全性チェック（接続、キャッシュ、ロック、レプリケーション、ブロート、すべて）

PostgreSQL拡張機能のセットアップ

HypoPG拡張機能

HypoPGは、実際にインデックスを作成せずにインデックスをテストできるようにします。これは、以下のような場合に非常に有用です。

• 提案されたインデックスがクエリプランナーによって使用されるかどうかをテストする。
• 異なるインデックス戦略で実行プランを比較する。
• コミットする前にストレージ要件を推定する。

データベースでHypoPGを有効にする

HypoPGは、ディスク上にインデックスを作成せずに仮想インデックスをテストできるようにします。

-- 拡張機能を作成
CREATE EXTENSION IF NOT EXISTS hypopg;

-- インストールを確認
SELECT * FROM hypopg_list_indexes();

pg_stat_statements拡張機能

pg_stat_statements拡張機能は、クエリパフォーマンス分析に必須です。サーバーで実行されるすべてのSQLステートメントの計画と実行統計を追跡します。

ステップ1: postgresql.confで拡張機能を有効にする

postgresql.confファイルに以下を追加します。

# 必須: pg_stat_statementsモジュールをロード
shared_preload_libraries = 'pg_stat_statements'

# 必須: クエリ識別子の計算を有効にする
compute_query_id = on

# 追跡する最大ステートメント数（デフォルト: 5000）
pg_stat_statements.max = 10000

# ネストされたステートメントを含むすべてのステートメントを追跡（デフォルト: top）
# オプション: top, all, none
pg_stat_statements.track = top

# CREATE、ALTER、DROPなどのユーティリティコマンドを追跡（デフォルト: on）
pg_stat_statements.track_utility = on

⚠️ 重要提示

shared_preload_librariesを変更した後、PostgreSQLサーバーの再起動が必要です。

ステップ2: データベースで拡張機能を作成する

-- データベースに接続して拡張機能を作成
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- インストールを確認
SELECT * FROM pg_stat_statements LIMIT 1;

pgstattuple拡張機能

pgstattuple拡張機能は、ブロート検出ツール（analyze_table_bloat、analyze_index_bloat、get_bloat_summary）に必須です。テーブルとインデックスのタプルレベルの統計を取得する関数を提供します。

-- 拡張機能を作成
CREATE EXTENSION IF NOT EXISTS pgstattuple;

-- インストールを確認
SELECT * FROM pgstattuple('pg_class') LIMIT 1;

パフォーマンス影響の考慮事項

💡 使用建议

track_io_timingを有効にする前に、pg_test_timingを使用して特定のシステムでのタイミングオーバーヘッドを測定してください。

💻 使用例

低速クエリを見つけて分析する

# 最も低速な上位10件のクエリを取得
slow_queries = await get_slow_queries(limit=10, order_by="total_time")

# 特定のクエリの実行プランを分析
analysis = await analyze_query(
    query="SELECT * FROM orders WHERE user_id = 123",
    analyze=True,
    buffers=True
)

インデックスの推奨事項を取得する

# ワークロードを分析して推奨事項を取得
recommendations = await get_index_recommendations(
    max_recommendations=5,
    min_improvement_percent=20,
    include_hypothetical_testing=True
)

# 推奨事項にはCREATE INDEXステートメントが含まれています
for rec in recommendations["recommendations"]:
    print(rec["create_statement"])

データベースの健全性チェック

# 包括的な健全性チェックを実行
health = await check_database_health(
    include_recommendations=True,
    verbose=True
)

print(f"健全性スコア: {health['overall_score']}/100")
print(f"ステータス: {health['status']}")

# 特定の領域をレビュー
for issue in health["issues"]:
    print(f"{issue}")

未使用のインデックスを見つける

# 削除できるインデックスを見つける
unused = await find_unused_indexes(
    schema_name="public",
    include_duplicates=True
)

# DROPステートメントを取得
for stmt in unused["recommendations"]:
    print(stmt)

Docker

docker pull  dog830228/pgtuner_mcp

# ストリーミング可能なHTTPモード（Webアプリケーションに推奨）
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http

# ストリーミング可能なHTTPステートレスモード（サーバーレス用）
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode streamable-http --stateless

# SSEモード（レガシーWebアプリケーション用）
docker run -p 8080:8080 \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode sse

# stdioモード（Claude DesktopなどのMCPクライアント用）
docker run -i \
  -e DATABASE_URI=postgresql://user:pass@host:5432/db \
  dog830228/pgtuner_mcp --mode stdio

要件

• Python: 3.10+
• PostgreSQL: 12+（推奨: 14+）
• 拡張機能:
  • pg_stat_statements（クエリ分析に必要）
  • hypopg（オプション、仮想インデックステスト用）

依存関係

コア依存関係

• mcp[cli]>=1.12.0 - Model Context Protocol SDK
• psycopg[binary,pool]>=3.1.0 - 接続プーリングを備えたPostgreSQLアダプター
• pglast>=7.10 - PostgreSQLクエリパーサー

オプション（HTTPモード用）

• starlette>=0.27.0 - ASGIフレームワーク
• uvicorn>=0.23.0 - ASGIサーバー

コントリビュート

コントリビューションは大歓迎です！プルリクエストを送信してください。