mcp-postgres

MCP-сервер для PostgreSQL. Предоставляет ИИ-агентам возможности анализа схемы, выполнения запросов и инструменты администрирования (DBA) через Model Context Protocol.

В отличие от универсальных MCP-серверов для баз данных, mcp-postgres создан специально для Postgres. Он извлекает комментарии к таблицам/столбцам, понимает специфические для Postgres системные представления, предоставляет анализ индексов и поставляется с настраиваемыми уровнями доступа, чтобы вы не предоставляли LLM неограниченный доступ к базе данных.

Возможности

Анализ схемы

• Список схем, таблиц и представлений с размерами и количеством строк

• Полное описание таблиц: столбцы, типы, ограничения, индексы, внешние ключи

• Извлечение метаданных COMMENT ON — дает LLM семантический контекст о назначении столбцов

• Поиск объектов по имени или комментарию во всей базе данных

Выполнение запросов

• Инструмент query только для чтения с автоматическим ограничением количества строк

• Инструмент execute для записи, ограниченный уровнем доступа

• EXPLAIN ANALYZE с удобным для чтения выводом

Инструменты DBA

• Статистика таблиц: живые/мертвые кортежи, процент раздувания (bloat), история очистки (vacuum), шаблоны сканирования

• Анализ индексов: статистика использования, обнаружение неиспользуемых индексов, рекомендации по отсутствующим индексам

• Состояние базы данных: соединения, коэффициент попаданий в кэш, длительные запросы, пропускная способность

Безопасность

• Четыре уровня доступа: readonly, readwrite, admin, unrestricted

• Классификация SQL-операторов (SELECT, DML, DDL, admin) с принудительным контролем

• Аудит-логирование в stderr (JSON, одна запись на запрос)

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

npx mcp-postgres --connection-string "postgres://user:pass@localhost:5432/mydb"

Или с переменными окружения:

DATABASE_URL="postgres://user:pass@localhost:5432/mydb" npx mcp-postgres

Claude Desktop

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres",
        "--connection-string",
        "postgres://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

Claude Code

Добавьте в файл .mcp.json вашего проекта:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Инструменты

*explain_query с параметром analyze=true выполняет запрос, поэтому он учитывает уровень доступа для данного оператора.

Ресурсы

Промпты

Конфигурация

Опции CLI

--connection-string  PostgreSQL connection URL
--access-level       readonly|readwrite|admin|unrestricted (default: readonly)
--row-limit          Max rows returned per query (default: 500)
--schema             Default schema filter (default: public)
--audit              Enable query audit logging to stderr

Переменные окружения

Уровни доступа

По умолчанию используется readonly. Используйте минимально необходимый уровень.

Аудит-логирование

Включите с помощью --audit. Логирует каждый вызов инструмента в stderr в формате JSON:

{"timestamp":"2026-04-03T12:00:00.000Z","tool":"query","sql":"SELECT * FROM users","statementType":"select","accessLevel":"readonly","allowed":true,"durationMs":12,"rowCount":42}

Перенаправьте stderr в файл для сохранения: mcp-postgres --audit 2>audit.log

Архитектура

src/
├── index.ts             Entry point and CLI
├── server.ts            MCP server setup
├── config.ts            Configuration parsing
├── db/
│   ├── pool.ts          Connection pool management
│   └── query.ts         Query execution with timing
├── tools/
│   ├── schema.ts        Schema exploration tools
│   ├── query.ts         Query execution tools
│   └── performance.ts   DBA and health tools
├── resources/
│   └── schema.ts        Schema DDL resources
├── prompts/
│   └── index.ts         Prompt templates
└── safety/
    ├── classifier.ts    SQL statement classification
    ├── access.ts        Access level enforcement
    └── audit.ts         Audit logging

Разработка

npm install
npm test           # run tests
npm run build      # compile TypeScript
npm run dev -- --connection-string "postgres://..."  # run in dev mode

Лицензия

MIT