postgres-mcp

📘 Postgres MCP Pro — сервер MCP для PostgreSQL

---

🔎 Обзор

Postgres MCP Pro — это open-source сервер Model Context Protocol (MCP), предназначенный для помощи разработчикам и AI-агентам на всех этапах разработки: от начального кода и тестирования до деплоя и продакшн-оптимизации.

🙌 Основано на crystaldba/postgres-mcp (MIT, © 2025 Crystal Corp / Johann Schleier-Smith). Форк развивается и поддерживается sparta2025 — автономный MCP-сервер, Gradio-оболочка, LLM-чат с tool-calling, сертификаты шифрования.

📚 Полная документация: docs/DOCUMENTATION.md — развёртывание (Docker/облако), Gradio-оболочка, подключение клиентов (stdio/SSE), все инструменты и переменные окружения.

Отличается от простого подключения к базе данных следующими возможностями:

• Анализ состояния БД: индекс, буферный кэш, autovacuum, последовательности, репликация и др.
• Оптимизация индексов: автоматический подбор лучших индексов с помощью промышленных алгоритмов.
• Планы выполнения: EXPLAIN и симуляция с гипотетическими индексами.
• Интеллект схемы: генерация SQL с учётом структуры базы.
• Безопасное выполнение SQL: поддержка режима только для чтения и защита в продакшне.

Поддерживает транспорты: stdio и SSE.

Запуск проекта и причины его создания

---

📺 Демонстрация

От медленного к молниеносному AI сгенерировал приложение на SQLAlchemy ORM — но оно было слишком медленным. Postgres MCP Pro с Cursor решил проблему за считанные минуты.

• 🚀 Оптимизация ORM-запросов, индексации и кэширования
• 🛠️ Исправление сломанной страницы
• 🧠 Улучшение вывода "топ-фильмов" путём анализа данных и корректировки запросов

👉 Подробнее: movie-app.md

---

⚡ Быстрый старт

Требования:

1. Доступ к вашей базе данных PostgreSQL
2. Docker или Python 3.12+

Удостоверьтесь в доступе:

Пример — подключение через psql или pgAdmin

💡 Для запуска через docker compose заранее создайте пустые файлы хранилищ подключений (иначе Docker смонтирует каталоги вместо файлов):

touch connections.json llm_connections.json

---

Установка

🐳 Docker

docker pull crystaldba/postgres-mcp

🐍 Python (через pipx)

pipx install postgres-mcp-pro

или через uv:

uv pip install postgres-mcp-pro

Консольная команда после установки — postgres-mcp (автономный MCP-сервер, stdio по умолчанию; --transport sse для SSE).

---

⚙️ Настройка AI-ассистента (на примере Claude Desktop)

Откройте конфигурационный файл:

• 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"
      }
    }
  }
}

Через pipx

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

Через uv

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

Режимы доступа:

• --access-mode=unrestricted: полный доступ (dev)
• --access-mode=restricted: только чтение (prod)

⚠️ Флаг --access-mode поддерживает только легаси-сервер (python -m postgres_mcp.server). Автономный MCP-сервер (postgres_mcp.autonomous.mcp_server) всегда выполняет переданный SQL; разграничение делайте на стороне пользователя БД.

---

🔄 SSE トランスポート

SSE を使用するには：

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

Cursor の例：

{
  "mcpServers": {
    "postgres": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

---

🧩 拡張機能のインストール（任意）

以下で必要です：

• pg_stat_statements — クエリの分析用
• hypopg — インデックスのシミュレーション用

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

---

🧪 使用例

• データベースの確認：「データベースの状態を確認してください……」
• 遅いクエリ：「最も遅いクエリは何ですか……」
• 推奨事項：「処理を速くするにはどうすればよいですか？」
• インデックス：「パフォーマンスを改善するインデックスを提案してください」
• クエリの最適化：「このクエリの最適化を手伝ってください：SELECT ...」

---

📡 MCP API（インターフェース）

自律型サーバー（postgres_mcp.autonomous.mcp_server）は、15 個の MCP ツールを提供します：

ツール	用途
list_schemas	データベースのスキーマ一覧
list_objects	テーブル、ビューなどの一覧
get_object_details	オブジェクトの詳細
execute_sql	SQL の実行
explain_query	クエリの EXPLAIN プラン
analyze_db_health	複数のメトリクスによるデータベースの健全性分析
get_top_queries	最も遅いクエリ（pg_stat_statements）
analyze_index_performance	インデックス使用状況の分析
get_active_queries	実行中のクエリ
get_table_sizes	テーブル／インデックスのサイズ
get_database_locks	現在のロック
format_sql_query	SQL のフォーマット（sqlparse）
get_database_info	バージョン、データベースのサイズ、拡張機能、稼働時間
manage_encryption_key	Fernet 証明書の管理
list_tools	サーバーの全ツール一覧

---

📌 他の MCP サーバーとの違い

Postgres MCP Pro	他の MCP サーバー
✅ 保証付きの健全性チェック	❌ LLM による生成
✅ アルゴリズムによるインデックス最適化	❌ 仮定に基づく提案
✅ EXPLAIN のシミュレーション	❌ 「自分で試してください」
✅ 詳細なワークロード分析	❌ クエリ分析なし

---

🧠 MCP ツールが必要な理由

LLM は SQL の生成に優れていますが、処理が遅く、コストが高く、予測できません。 データベースの最適化は、以前からアルゴリズムで解決されています。 MCP Pro は、LLM と従来のアルゴリズムの長所を組み合わせます。

---

🛠️ 技術的な注意事項（主なポイント）

• インデックス：pg_stat_statements の使用、候補の生成、hypopg による分析
• LLM による最適化：実験的機能であり、OpenAI API（OPENAI_API_KEY）を使用します
• データベースの健全性：PgHero のチェックを適用
• 接続ライブラリ：libpq を使用する psycopg3
• SQL の安全性：読み取り専用、ROLLBACK; DROP ... への対策
• スキーマとの連携：リソースではなくツールを介して、エージェントにスキーマを渡します
• 接続の設定：環境変数を使用
• 開発ビルド：uv、pip、ローカルデータベースでの起動