pgmcp

pgmcp — это сервер операций/администрирования PostgreSQL только для чтения для Model Context Protocol, построенный на официальном modelcontextprotocol/go-sdk. Он отвечает на вопросы, которые DBA задаёт во время инцидента — какие операторы медленные, почему этот план медленный, какие индексы — мёртвый груз, за какими таблицами autovacuum отстал, кто кого блокирует, насколько отстаёт резервный сервер — и он доступен только для чтения по конструкции, а не по соглашению: выделенная роль базы данных без права записи, транзакция BEGIN READ ONLY с таймаутом оператора для каждого оператора и защита парсера SQL, которая отклоняет всё, что не является одним SELECT/EXPLAIN/SHOW, и каждую функцию, которая может изменить состояние внутри транзакции только для чтения. Протестировано на PostgreSQL 16; требуется версия 13 или новее.

Установка

Claude Desktop, в один клик: скачайте pgmcp_<version>.mcpb из Releases и откройте его. Claude Desktop запросит строку подключения к Postgres, сохранит её в связке ключей ОС и сам запустит встроенный бинарник — ничего на PATH, никаких файлов конфигурации для правки. Один пакет покрывает macOS (универсальный) и Windows (x64).

В противном случае скачайте бинарник для вашей платформы из Releases — darwin, linux и windows, amd64 и arm64, с контрольными суммами.

Или соберите из исходников с помощью Go CLI-инструмента go:

go install github.com/pascalallen/pgmcp/cmd/pgmcp@latest

Или запустите выпущенный образ, который является distroless, без root-прав и мультиархитектурным:

docker run --rm -i -e PGMCP_DATABASE_URL='postgres://…' ghcr.io/pascalallen/pgmcp

pgmcp указан в реестре MCP как io.github.pascalallen/pgmcp.

Прежде чем направить его на что-либо, создайте роль только для чтения — см. Роль базы данных. Это слой, который остаётся надёжным, даже если в двух других есть ошибка.

Related MCP server: PostgreSQL MCP Server

Использование

Одна MCP-поверхность, два транспорта. Какой из них запускать — это конфигурация, а не другая сборка.

Claude Code, stdio — клиент запускает бинарник и общается через stdin/stdout:

claude mcp add pgmcp --transport stdio \
  --env PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
  -- pgmcp

Claude Desktop, stdio — установите пакет .mcpb из Releases (см. Установка), или впишите то же самое в claude_desktop_config.json вручную:

{
  "mcpServers": {
    "pgmcp": {
      "command": "pgmcp",
      "env": {
        "PGMCP_DATABASE_URL": "postgres://pgmcp:…@db.internal:5432/app?sslmode=require"
      }
    }
  }
}

HTTP — Streamable HTTP за статическим bearer-ключом, для общего развёртывания. pgmcp говорит на чистом HTTP и сам не завершает TLS; запускайте его на loopback за обратным прокси.

PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
PGMCP_AUTH_MODE=static \
PGMCP_API_KEYS="$(openssl rand -hex 32)" \
  pgmcp --transport http --listen 127.0.0.1:8080

claude mcp add pgmcp --transport http https://pgmcp.example.com/mcp \
  --header "Authorization: Bearer <key>"

Завершение TLS, настройки прокси, необходимые потоковому транспорту, JWT-аутентификация против провайдера идентификации и подключение pgmcp как пользовательского коннектора claude.ai — всё это в docs/DEPLOYING.md.

Инструменты

Каждый инструмент аннотирован readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false и возвращает типизированную схему вывода.

query — единственный инструмент, который несёт свободный SQL, и он необязателен. --disable-query полностью убирает его из каталога — развёртывание, которому нужны только восемь диагностических инструментов, может работать вообще без какой-либо ad hoc SQL-поверхности. --query-schemas=public,app вместо этого ограничивает его именованными схемами — и ограничивает explain вместе с ним, поскольку analyze=true выполняет оператор; прочитайте, что это останавливает и что не останавливает, в docs/SECURITY.md.

Ресурсы и промпт

Блок аутентификации применяется только к HTTP-транспорту. Через stdio операционная система решает, кто является вызывающей стороной: родительский процесс, запустивший бинарный файл, и никто другой.

Модель безопасности

• Только чтение, тремя независимыми способами. Выделенная роль без права записи (pg_monitor плюс SELECT, и намеренно не pg_signal_backend); BEGIN READ ONLY с SET LOCAL statement_timeout и lock_timeout = '2s' вокруг каждого оператора, выполняемого адаптером, всегда с откатом; и защита на уровне парсера, потому что только транзакции только для чтения недостаточно, чтобы остановить pg_terminate_backend, pg_read_file, pg_sleep или setval.

• SQL-защита построена по принципу «сначала разрешённое». Один оператор верхнего уровня, и он должен быть SELECT, EXPLAIN или SHOW; никаких вложенных операторов записи в дереве; никакого предложения блокировки FOR UPDATE/FOR SHARE; никакого SELECT INTO; и никаких вызовов запрещённых функций — доступ к файлам, управление резервным копированием и WAL, слоты репликации, advisory locks, dblink, изменение последовательностей, сброс статистики.

• Список разрешённых схем — это ограждение, а не граница. --query-schemas сопоставляет схемы, определяющие ссылки на таблицы в разобранном операторе, без учёта регистра, и ограничивает оба инструмента, которые принимают SQL от вызывающей стороны — query и explain, так что explain с analyze=true не может выполняться против схемы, которую вы исключили. Представление, функция, возвращающая набор строк, или функция SECURITY DEFINER внутри разрешённой схемы всё ещё может читать данные за её пределами. Границей являются привилегии базы данных; список разрешённого лишь сужает очевидный путь.

• Аутентифицировано, закрыто при сбое, через HTTP. Статические ключи сравниваются за постоянное время с каждым сохранённым хэшем без раннего выхода; JWT проверяются против набора JWK только с асимметричными алгоритмами (без alg=none, без путаницы с HMAC) и обязательными iss, aud и exp, и проверяющий не хранит ключи до получения JWKS, поэтому он начинает в закрытом состоянии, а не в открытом. Защищённые метаданные ресурса RFC 9728 сообщают, где получить токен. Сервер отказывается запускаться на адресе, отличном от loopback, при выключенной аутентификации.

• Ограничено. Ограничение скорости на каждого субъекта, таймаут на каждый вызов, таймаут оператора и таймаут блокировки внутри транзакции, ограничение на количество строк в инструменте query, ограничение на структурированное содержимое результата и ограничение размера тела запроса в 1 МиБ.

• Ничего чувствительного не логируется. Вызов инструмента логирует его имя, длительность, результат и идентификатор пользователя вызывающей стороны — никогда аргументы, текст SQL, строки результата или текст ошибки. Ошибки разбора возвращаются фиксированной фразой, а не повторением оператора, а DSN удаляется из ошибок подключения.

Модель угроз, полный перечень уровней и ограничения, которые каждый из них не покрывает, находятся в docs/SECURITY.md.

Тестирование

Запустите набор тестов с детектором гонок и покрытием:

go test -race -cover ./...

Интеграционные тесты требуют базу данных Postgres и пропускаются, когда PGMCP_TEST_DSN не задан. Чтобы запустить их против временной Postgres с предзагруженным pg_stat_statements:

docker run -d --rm --name pg -e POSTGRES_PASSWORD=postgres -p 5544:5432 postgres:16 \
  -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all
docker exec pg psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements"
PGMCP_TEST_DSN="postgres://postgres:postgres@localhost:5544/postgres?sslmode=disable" go test -race -cover ./...

Создайте и просмотрите профиль покрытия:

go test -covermode=count -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Проверьте запущенный сервер через официальный набор соответствия MCP или протестируйте его с помощью Inspector:

npx -y @modelcontextprotocol/conformance server --url http://127.0.0.1:8080/mcp \
  --expected-failures .github/conformance-expected-failures.yaml
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http --method tools/list

Вклад

Приветствуются pull request'ы. Для значительных изменений, пожалуйста, сначала откройте issue, чтобы обсудить, что вы хотели бы изменить.

Пожалуйста, не забудьте обновить тесты по мере необходимости.

Лицензия

MIT