PG-MCP Server
MCP-сервер для PostgreSQL с несколькими базами сразу, описаниями таблиц из каталога, подсказками по PostGIS и pgvector и планами запросов
- 540 ★ репозитория
- Последний коммит
- MIT
Расширенный доступ
Почему такой уровень
- Подключается к базам PostgreSQL по строке с логином и паролем, которую агент передает в диалоге
- Читает таблицы и образцы данных и записывает текст запросов в журнал уровня DEBUG
- Слушает порт 8000 на всех сетевых интерфейсах без проверки доступа
Установка
- Работает в
Ручная установка
docker-compose up -dВыполняется в склонированном репозитории `https://github.com/stuzero/pg-mcp-server.git`, сервер слушает порт 8000.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Подключается к базам PostgreSQL по строке с логином и паролем, которую агент передает в диалоге
- Читает таблицы и образцы данных и записывает текст запросов в журнал уровня DEBUG
- Слушает порт 8000 на всех сетевых интерфейсах без проверки доступа
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Сервер на Python поднимается как HTTP-приложение с транспортом SSE на порту 8000 и обслуживает сразу несколько баз PostgreSQL. Агент вызывает инструмент `connect` со строкой подключения и получает в ответ идентификатор соединения `conn_id`. Дальше все запросы идут по этому идентификатору, а `disconnect` закрывает пул. Запросы выполняют два инструмента. `pg_query` перед каждым запросом включает транзакцию только на чтение и возвращает строки списком словарей, `pg_explain` оборачивает запрос в `EXPLAIN (FORMAT JSON)` и отдает план целиком. Схему агент читает через ресурсы с адресами `pgmcp://{conn_id}/schemas`: схемы, таблицы с числом строк и описаниями из каталога базы, колонки, ограничения, индексы, расширения и постраничные образцы данных. Для расширений PostGIS и pgvector в каталоге `server/resources/extensions` лежат YAML-справки с типами, функциями и примерами, новые добавляются отдельными файлами. Четыре готовых промпта (`generate_sql`, `validate_nl`, `justify_sql` и `generate_vega`) ведут агента от вопроса на естественном языке к SQL и спецификации графика Vega-Lite.
Для кого. Для разработчиков и аналитиков, которые работают с PostgreSQL, держат несколько баз и хотят, чтобы агент сам изучал схему и писал запросы только на чтение.
Подходит, если
- Рабочих баз несколько, и агенту нужно переключаться между ними в одном сеансе, не перезапуская сервер
- Схема плохо документирована, и агенту нужны описания таблиц и колонок, которые уже записаны в каталоге PostgreSQL
- В базе есть PostGIS или pgvector, и агент должен знать их типы и функции, прежде чем писать запрос
- Нужно перевести вопрос на русском или английском в SQL и сразу получить спецификацию графика Vega-Lite
Не подходит, если
- Нужен запуск командой в конфигурации клиента без отдельного сервера: здесь сервер ждет подключений по HTTP и поднимается заранее
- Нужны подбор индексов и проверка здоровья базы: такую роль описывает карточка postgres-mcp
- Установлен Python старше 3.13 и нет Docker: проект требует версию 3.13 или новее
- Нужен инструмент для MySQL, SQL Server или SQLite: сервер работает только с PostgreSQL
- Нужно изменять данные или схему: запросы идут в транзакции только на чтение
Пример запроса к агенту
Подключись к базе продаж, найди таблицы с заказами и покажи пять клиентов с самой большой суммой покупок, а потом объясни план этого запросаMCP
- Транспорт
- sse
- Авторизация
- не нужна
Переменные окружения
LOG_LEVEL- Уровень журнала сервера, по умолчанию DEBUG
PG_MCP_URL- Адрес SSE для демонстрационных клиентов, например `http://localhost:8000/sse`
Ограничения
Проект версии 0.1.0, последнее изменение в репозитории от 10 сентября 2025 года. Лицензия MIT.
Строку подключения агент передает инструментом `connect`, поэтому логин и пароль базы проходят через диалог с моделью, а не лежат в конфигурации клиента. Сервер хранит соответствие идентификаторов и строк подключения в памяти процесса.
Уровень журнала по умолчанию DEBUG, в `docker-compose.yml` он тоже выставлен на DEBUG, а текст каждого запроса записывается в журнал вместе с идентификатором соединения.
Защита от записи держится на команде `SET TRANSACTION READ ONLY`: добавьте к ней ограничение прав учетной записи базы.
Порт 8000 слушает все сетевые интерфейсы (`0.0.0.0`), своей проверки доступа у сервера нет. Каталог `server` из `docker-compose.yml` смонтирован в контейнер для разработки с перезагрузкой кода.
Как отключить. Остановите контейнер командой `docker-compose down` или завершите процесс `python -m server.app`, затем удалите адрес сервера из настроек клиента. Если соединения были открыты, вызовите `disconnect` для каждого идентификатора.
Частые вопросы
Как запустить сервер?
Склонируйте репозиторий и выполните `docker-compose up -d`: контейнер откроет порт 8000. Без Docker достаточно команды `uv sync`, активации среды `.venv` и запуска `python -m server.app`. Нужен Python 3.13 или новее.
По какому адресу подключать клиент?
Пример в репозитории использует `http://localhost:8000/sse`: этот адрес записан в переменной `PG_MCP_URL` для демонстрационных клиентов.
Что вернет connect и зачем нужен conn_id?
Инструмент регистрирует строку подключения и возвращает непрозрачный идентификатор. В адресах ресурсов и запросах используется он, а не сама строка, поэтому логин и пароль не светятся в адресах `pgmcp://`.
Можно ли запустить сервер для нескольких баз сразу?
Да. Каждый вызов `connect` создает отдельное соединение со своим идентификатором, и агент выбирает базу, подставляя нужный `conn_id`.
Как проверить сервер без своего агента?
Скрипт `test.py` принимает строку подключения аргументом. Для проверки запросов на естественном языке есть `example-clients/claude_cli.py`, который берет `ANTHROPIC_API_KEY`, `DATABASE_URL` и `PG_MCP_URL` из файла `.env`.
Какие еще демонстрационные клиенты есть?
Кроме клиента для Claude, в папке `example-clients` лежат `gemini-agent-cli.py` и `ollama_cli.py` для запуска с Gemini и локальными моделями Ollama.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыpgEdge Postgres MCP
pgEdge Postgres MCP Server
Postgres MCP на Go с запросами в режиме чтения, планами EXPLAIN, поиском по смыслу, несколькими базами, чат-клиентом и веб-интерфейсом
MCP-сервер и скиллы от TigerData, с которыми агент пишет схемы и запросы PostgreSQL по актуальной документации и практикам
Postgres MCP (Microsoft)
Postgres MCP Server (Microsoft)
Postgres MCP от Microsoft: профили подключения с паролями в связке ключей ОС, вход через Entra ID для Azure, запросы, схема, CSV и метрики сервера
MCP-сервер и REST API для баз данных на Go: PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery и других, с маскировкой персональных данных и кэшем
MCP-сервер на Python для работы с MySQL: список таблиц, чтение данных, выполнение SQL и разбор схемы через контролируемый интерфейс
Открытый MCP-сервер Google для баз данных: готовые инструменты для Postgres, MySQL, BigQuery, Spanner и других, плюс свои инструменты в tools.yaml
Сравнение с похожими
Записи с тем же главным запросом: чем они отличаются.
| Запись | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| PG-MCP Server (эта запись) | нет | не нужна | 540 | |
| Postgres MCP Pro | нет | API-ключ | 3 418 | сервер с подбором индексов, проверкой здоровья базы и запуском через uvx или Docker |
| DBHub | нет | не нужна | 3 703 | один сервер для PostgreSQL, MySQL, MariaDB, SQL Server и SQLite с режимом только чтения и SSH-туннелем |
| pgEdge Postgres MCP | нет | не нужна | 239 | postgres MCP на Go с запросами в режиме чтения |
Коротко о README
В репозитории описано, чем сервер расширяет эталонную реализацию PostgreSQL для MCP: транспорт SSE, несколько баз, описания из каталога, справки по расширениям, разбор плана запроса и управление соединениями. Приведены способы запуска через Docker Compose и вручную, пример промпта для агента и перечень адресов ресурсов. Рядом лежат демонстрационные клиенты для Claude, Gemini и Ollama, скрипт `test.py`, шаблон `.env.example` и каталоги `server`, `prompts` и `resources` с исходниками.