📘 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

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

Требования:

Доступ к вашей базе данных PostgreSQL
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 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:

{
  "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;

🧪 Примеры использования

Проверка БД: "Check the health of my database..."
Медленные запросы: "What are the slowest queries..."
Рекомендации: "How can I make it faster?"
Индексы: "Suggest indexes to improve performance"
Оптимизация запроса: "Help me optimize this query: SELECT ..."

📡 MCP API (интерфейс)

Автономный сервер (postgres_mcp.autonomous.mcp_server) предоставляет 15 MCP tools:

Tool	Назначение
`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`	Версия, размер БД, расширения, uptime
`manage_encryption_key`	Управление Fernet-сертификатами
`list_tools`	Список всех инструментов сервера

📌 Отличия от других MCP-серверов

Postgres MCP Pro	Другие MCP-серверы
✅ Проверки здоровья с гарантией	❌ Генерация LLM
✅ Оптимизация индексов алгоритмом	❌ Гипотетические советы
✅ Симуляции EXPLAIN	❌ "Попробуй сам"
✅ Детальный workload-анализ	❌ Нет анализа запросов

🧠 Почему нужны инструменты MCP?

LLM отлично справляется с генерацией SQL, но медленно, дорого и непредсказуемо. Оптимизация БД давно решается алгоритмами. MCP Pro сочетает лучшее от LLM и классических алгоритмов.

🛠️ Технические заметки (ключевые моменты)

Индексы: использование pg_stat_statements, генерация кандидатов, анализ через hypopg
LLM-оптимизация: экспериментальная, с использованием OpenAI API (OPENAI_API_KEY)
Здоровье БД: адаптация проверок из PgHero
Библиотека подключения: psycopg3 с libpq
Безопасность SQL: чтение, защита от ROLLBACK; DROP ...
Интеграция со схемой: передаёт схему агенту через инструменты, а не ресурсы
Конфигурация соединений: через переменные среды
Dev-сборка: uv, pip, запуск с локальной БД

postgres mcp