Postgres MCP Server (Postgres MCP Pro)

Postgres MCP Server (Postgres MCP Pro) とは？

Postgres MCP Pro は、Crystal DBA が開発したオープンソースの postgres mcp server で、PostgreSQL 向けに安全な SQL 実行、スキーマインテリジェンス、EXPLAIN プラン、データベースのヘルスチェック、インデックスチューニングを AI エージェントに提供します。

単なるデータベース接続のラッパーではありません。クエリの実行に加えて、パフォーマンス改善のための決定的なツールを備えています。pg_stat_statements で遅いクエリを見つけ、hypopg で仮想インデックスをシミュレートし、ワークロードに合ったインデックス構成を探索します。制限付きの読み取り専用アクセスモードにより、本番データベースにも使えます。MIT ライセンスで、PyPI では postgres-mcp、Docker Hub では crystaldba/postgres-mcp として公開されており、stdio と SSE の両方のトランスポートに対応しています。

Postgres MCP Server (Postgres MCP Pro) の使い方

前提条件：PostgreSQL の接続 URI（事前に psql や pgAdmin で確認してください）と、Docker または Python 3.12 以上。Python でのインストールは環境依存の問題が起きやすいため、メンテナーは一般的に Docker を推奨しています。

いずれかの方法でインストールします。

docker pull crystaldba/postgres-mcp
# or
pipx install postgres-mcp
# or
uv pip install postgres-mcp

アクセスモードを選びます。--access-mode=unrestricted はデータとスキーマへの完全な読み書きを許可し（開発環境向け）、--access-mode=restricted はエージェントを読み取り専用トランザクションに制限し、実行時間に上限を設けます（本番環境向け）。

Claude Desktop

claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%/Claude/claude_desktop_config.json）。Docker を使う場合：

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

Docker イメージは localhost を自動的に置き換えます（macOS/Windows では host.docker.internal、Linux では 172.17.0.1 または適切なホストアドレス）。uvx を使う場合：

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

pipx でインストールした場合は "command": "postgres-mcp"、uv の場合は "command": "uv" と "args": ["run", "postgres-mcp", "--access-mode=unrestricted"] を使います。

Claude Code

Claude Code CLI で同じ stdio コマンドを追加します。

claude mcp add postgres \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  -- uvx postgres-mcp --access-mode=restricted

Cursor

コマンドパレットから Cursor Settings を開き、MCP タブで上記の mcpServers ブロックのいずれかを貼り付けます。Windsurf（Open Windsurf Settings Page）、Goose（goose configure → Add Extension）、Qodo Gen も同じ設定を使います。

SSE トランスポート（共有またはリモートサーバー）

--transport=sse を付けてサーバーを起動します。

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

その後、Cursor（mcp.json）や Cline で {"type": "sse", "url": "http://localhost:8000/sse"} を指定して接続します。Windsurf では url の代わりに serverUrl を使います。

オプションの拡張機能

インデックスチューニングとワークロード分析には pg_stat_statements と hypopg を有効にします。AWS RDS、Azure、Google Cloud SQL などのマネージドサービスでは、通常すでに利用可能です。

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Postgres MCP Server (Postgres MCP Pro) の主な機能

• データベースのヘルスチェック：インデックスの健全性（重複・未使用・無効）、接続の使用率、バッファキャッシュのヒット率、vacuum の状態、シーケンスの上限、制約の検証、レプリケーション遅延。
• Microsoft の Anytime アルゴリズムをもとにしたインデックスチューニング。多数の候補インデックスを探索し、性能向上とストレージコストを比較します。
• EXPLAIN プラン。インデックスを実際に作成する前に、仮想インデックスの効果をシミュレートできます。
• コンテキストに沿った SQL 生成のためのスキーマインテリジェンス。
• restricted（読み取り専用）と unrestricted のアクセスモードと安全な SQL パースによる、安全な SQL 実行。
• すべての機能を MCP リソースではなく MCP ツールとして提供し、幅広いクライアントに対応。
• stdio と SSE のトランスポート、Docker と Python によるインストール。

Postgres MCP Server (Postgres MCP Pro) のツール

• スキーマの探索： list_schemas、list_objects（テーブル、ビュー、シーケンス、拡張機能）、get_object_details（カラム、制約、インデックス）。
• クエリの実行： execute_sql。restricted モードでは読み取り専用です。
• クエリプラン： explain_query は実行計画を返し、仮想インデックスを含めることもできます。
• パフォーマンス分析： get_top_queries は pg_stat_statements から最も遅いクエリを報告し、analyze_workload_indexes はワークロード全体に対して、analyze_query_indexes は指定した最大 10 件のクエリに対してインデックスを推奨します。
• ヘルス： analyze_db_health はすべてのヘルスチェックを実行します。

Postgres MCP Server (Postgres MCP Pro) のユースケース

• ヘルスチェック： "Check the health of my database and identify any issues."
• 遅いクエリの調査： "What are the slowest queries in my database? And how can I speed them up?"
• インデックスの推奨： "Analyze my database workload and suggest indexes to improve performance."
• クエリの最適化： "Help me optimize this query: SELECT * FROM orders JOIN customers ON ..."
• エディタでの ORM パフォーマンス修正： プロジェクトのデモでは、Cursor を使って生成されたアプリの遅い SQLAlchemy クエリを修正しています。
• スキーマを踏まえた開発： 慣れないスキーマを調べ、それに合った SQL を生成します。

Postgres MCP Server (Postgres MCP Pro) と代替ツールの比較

• リファレンス版 PostgreSQL MCP サーバー： Model Context Protocol の元々のリファレンスサーバーで、現在はアーカイブ済みのリポジトリにあります。スキーマを MCP リソースとして公開し、読み取り専用クエリのみを実行します。Postgres MCP Pro はツールを使い、ヘルスチェック、EXPLAIN 分析、インデックスチューニングを追加しています。
• Supabase MCP Server： 汎用的な PostgreSQL のパフォーマンスチューニングではなく、Supabase プロジェクト向けの管理機能を提供します。
• その他のコミュニティ製 postgresql mcp サーバー（いくつかは同じく postgres-mcp という名前です）は、主にクエリの実行とテーブル一覧の取得を行います。インストール前にパッケージ名と作者を確認してください。

Postgres MCP Server (Postgres MCP Pro) のトラブルシューティング

• Docker からローカルのデータベースに接続できない： イメージは localhost を置き換えますが、まずホスト上で psql を使って URI が有効か確認し、Postgres が Docker ネットワークからの接続を受け付けているかも確認してください。
• インデックスチューニングや遅いクエリのツールが失敗する： pg_stat_statements と hypopg をインストールします。自己管理の Postgres では、pg_stat_statements を shared_preload_libraries に追加する必要があり、hypopg はシステムパッケージでのインストールが必要な場合があります。
• 書き込みが拒否される： サーバーが restricted モードです。--access-mode=unrestricted への切り替えは開発環境だけにしてください。
• Python のインストールエラー： Python 3.12 以上が必要です。代わりに Docker イメージを試してください。
• SSE クライアントが接続できない： コンテナがポートを公開しているか（-p 8000:8000）、クライアントが /sse を使っているかを確認します。Windsurf では serverUrl が必要です。