📘 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, запуск с локальной БД
Metadata
Release files for postgres-mcp-pro 0.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| postgres_mcp_pro-0.4.2.tar.gz | 446.4 kB | Without provenance | Details for postgres_mcp_pro-0.4.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| postgres_mcp_pro-0.4.2-py3-none-any.whl | Python 3 | none | any | Details for postgres_mcp_pro-0.4.2-py3-none-any.whl |
Total release size: 669.8 kB
Release files / postgres_mcp_pro-0.4.2.tar.gz
| Download URL | postgres_mcp_pro-0.4.2.tar.gz |
|---|---|
| Size | 446.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c7164a6caf0de0b4f9a8d17d70244b47cc67019f546f4fae057d9851b76b4111
|
|
BLAKE2b-256 checksum How to use checksums |
0587b8d4a0d388cb7604f14fff2b850f1651f48a345d43a80189849ee9cadc33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.4 {"installer":{"name":"uv","version":"0.12.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / postgres_mcp_pro-0.4.2-py3-none-any.whl
| Download URL | postgres_mcp_pro-0.4.2-py3-none-any.whl |
|---|---|
| Size | 223.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bf71f4960c72c5c29e8cc4901d3e742f8c1d283133a1e3968a123213b82aee15
|
|
BLAKE2b-256 checksum How to use checksums |
c8613607739183caf43e8a19b17d985d80e7c8c23bf68b91fe57c38d18cf1dd1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.4 {"installer":{"name":"uv","version":"0.12.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for postgres-mcp-pro 0.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.