PostgreSQL Performance MCP

PostgreSQL Analyzer MCP

PostgreSQL データベースのパフォーマンス分析と最適化を行う Model Context Protocol（MCP）サーバーです。

概要

PostgreSQL Analyzer MCP は、AI を活用して、データベース管理者や開発者による PostgreSQL データベースの最適化を支援する強力なツールです。データベース構造、クエリのパフォーマンス、インデックスの使用状況、設定を包括的に分析し、改善に向けた実用的な推奨事項を提供します。

このツールは Streamable HTTP トランスポートを使用するリモート MCP サーバーとして動作するため、中央に配置し、Amazon Q Developer CLI、Claude、MCP プロトコルに対応するその他の AI アシスタントなど、あらゆる MCP 対応クライアントからアクセスできます。

⚠️ 免責事項

実験的プロジェクト：このプロジェクトは実験的なもので、MCP と PostgreSQL で実現できることを示すデモとして提供されています。本番環境に実装する前に、すべての推奨事項とコードを慎重に確認してください。

非公式プロジェクト：これは個人プロジェクトであり、私が勤務または貢献している組織との提携、承認、代表を意味するものではありません。意見や手法はすべて私個人のものです。

免責：このツールは、いかなる種類の保証もなく「現状有姿」で提供されます。ご自身の責任でご使用ください。本ソフトウェアの使用に起因する損害や問題について、作者は責任を負いません。

機能

• データベース構造の分析：テーブル、列、インデックス、外部キーを分析します
• クエリパフォーマンスの分析：実行計画を分析し、ボトルネックを特定します
• インデックスの推奨：クエリパターンに基づいて、新しいインデックスの候補を提案します
• クエリの最適化：パフォーマンス向上のためのクエリ書き換え案を提案します
• 低速クエリの特定：実行速度の遅いクエリを見つけて分析します
• データベース健全性ダッシュボード：データベースの健全性指標を包括的に確認できます
• インデックス使用状況の分析：未使用、重複、肥大化したインデックスを特定します
• 読み取り専用クエリの実行：確認のための読み取り専用クエリを安全に実行します

セキュリティ

このツールは、デフォルトで読み取り専用モードで動作します。データベースへの意図しない変更を防ぐため、すべてのデータベース接続で SET TRANSACTION READ ONLY を設定します。クエリ実行機能は SELECT、EXPLAIN、SHOW コマンドに厳密に制限されています。

インストール

前提条件

• Python 3.12+（または Docker）
• Amazon Aurora または RDS PostgreSQL データベース
• AWS アカウント（Secrets Manager を使用する場合。任意）

セットアップ

オプション 1：ローカルでのセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/yourusername/postgres-performance-mcp.git
   cd postgres-performance-mcp
   

2. 仮想環境を作成し、依存関係をインストールします：

   python -m venv venv
   source venv/bin/activate 
   pip install -r requirements.txt
   

オプション 2：Docker でのセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/yourusername/postgres-performance-mcp.git
   cd postgres-performance-mcp
   

2. Docker イメージをビルドします：

   docker build -t postgres-analyzer-mcp -f Dockerfile .
   

3. Docker コンテナを起動します：

   docker run -p 8000:8000 postgres-analyzer-mcp
   

   AWS 認証情報を使用する場合（Secrets Manager を使用する場合）：

   docker run -p 8000:8000 \
     -e AWS_ACCESS_KEY_ID=your_access_key \
     -e AWS_SECRET_ACCESS_KEY=your_secret_key \
     -e AWS_DEFAULT_REGION=your_region \
     postgres-analyzer-mcp
   

4. データベースの認証情報を設定します：

   • オプション 1：AWS Secrets Manager に認証情報を保存します（推奨）
   • オプション 2：ツールの使用時に認証情報を直接指定します

使い方

サーバーの起動

ローカル：

python src/main.py --host 0.0.0.0 --port 8000

Docker：

# The server starts automatically when running the container
docker run -p 8000:8000 postgres-analyzer-mcp

MCP クライアントの設定

リモート MCP サーバーに接続するには、次のように MCP クライアントを設定します：

Server URL: http://your-server-address:8000/mcp
Transport: Streamable HTTP

MCP クライアントでの使用

MCP 対応クライアントを使ってサーバーに接続し、利用可能なツールを使用します：

analyze_database_structure(secret_name="my-postgres-db-credentials", region_name="us-west-2")

利用可能なツール

• analyze_database_structure：データベーススキーマを分析し、最適化の推奨事項を提示します
• get_slow_queries：データベース内で実行速度の遅いクエリを特定します
• analyze_query：SQL クエリを分析し、最適化の推奨事項を提示します
• recommend_indexes：指定された SQL クエリに適したインデックスを推奨します
• suggest_query_rewrite：SQL クエリの最適化された書き換えを提案します
• database_health_dashboard：データベースの包括的なヘルスダッシュボードを生成します
• query_optimization_wizard：SQL クエリを段階的に最適化するための対話型ウィザードです
• analyze_index_usage：インデックスの使用パターンを分析し、未使用または効率の悪いインデックスを特定します
• execute_read_only_query：読み取り専用の SQL クエリを実行し、結果を返します
• show_postgresql_settings：オプションのフィルタリングを適用して PostgreSQL の設定を表示します
• health_check：サーバーが稼働中で応答可能かどうかを確認します

カスタマイズ

このツールの真価は、使用する環境に合わせてカスタマイズすることで発揮されます。

• データベースの使用パターンに合わせたカスタム分析ルールを追加する
• 監視システムと統合する
• 組織のベストプラクティスに基づいて推奨事項をカスタマイズする
• データモデルに関するドメイン固有の知識を追加する
• 必要に応じて、さらにツールを追加して拡張する

AWS Secrets Manager のセットアップ

データベースの認証情報を保存するために AWS Secrets Manager を使用するには、次の手順に従います。

1. AWS Secrets Manager に以下のキーを含むシークレットを作成します。

   • host：データベースのホスト名
   • port：データベースのポート（通常は 5432）
   • dbname：データベース名
   • username：データベースのユーザー名
   • password：データベースのパスワード

2. シークレットにアクセスするための適切な権限を持つように、AWS 認証情報が設定されていることを確認します。

3. ツールを呼び出す際にシークレット名を使用します。

   analyze_query(query="SELECT * FROM users WHERE user_id = 123", secret_name="my-postgres-db-credentials")
   

PostgreSQL の設定

パフォーマンス分析を最適に行うため、以下の拡張機能を有効にすることをおすすめします。

CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_buffercache;

また、postgresql.conf に以下の設定を追加します。

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

例

データベース構造の分析

analyze_database_structure(secret_name="my-postgres-db-credentials")

クエリの分析

analyze_query(
    query="SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.status = 'pending'",
    secret_name="my-postgres-db-credentials"
)

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

recommend_indexes(
    query="SELECT * FROM products WHERE category = 'electronics' AND price < 100",
    secret_name="my-postgres-db-credentials"
)

読み取り専用クエリの実行

execute_read_only_query(
    query="SELECT schemaname, relname, n_live_tup FROM pg_stat_user_tables ORDER BY n_live_tup DESC LIMIT 10",
    secret_name="my-postgres-db-credentials"
)

リモートサーバーへのデプロイ

MCP サーバーをリモートマシンにデプロイするには、次の手順に従います。

1. リモートサーバーに Docker をインストールします
2. プロジェクトファイルをサーバーにコピーするか、リポジトリからクローンします
3. Docker コンテナをビルドして実行します。

   docker build -t postgres-analyzer-mcp -f Dockerfile .
   docker run -d -p 8000:8000 postgres-analyzer-mcp
   

4. サーバーの再起動時にコンテナも再起動するように、docker-compose や systemd などのプロセスマネージャーの使用を検討します

安全にアクセスするため、以下の設定を検討してください。

• SSL/TLS を使用するリバースプロキシ（Nginx や Traefik など）
• 認証ミドルウェア
• アクセスを制限するファイアウォールルール

貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

謝辞

• ドキュメントを提供してくださった PostgreSQL コミュニティ
• AI 搭載ツールを可能にしてくださった MCP プロトコルの開発者
• このプロジェクトは、堅牢で保守しやすいソフトウェアを作成するために人間の専門知識と AI の能力を組み合わせる、AI 支援の開発手法であるバイブコーディングを使用して作成されました。