pg-mcp

Сервис для запросов к PostgreSQL на естественном языке через MCP (Model Context Protocol). Использует OpenAI для перевода естественного языка в SQL, проверяет и безопасно выполняет его, а также возвращает результаты любому клиенту, совместимому с MCP.

Возможности

• Перевод естественного языка в SQL через OpenAI

• Автоматическое обнаружение схемы базы данных при запуске (таблицы, представления, столбцы, индексы, внешние ключи, перечисления)

• Кэш схемы с опциональным сохранением на диск

• Проверка безопасности SQL (только SELECT, блокировка опасных функций, принудительное ограничение LIMIT)

• Выполнение транзакций только для чтения с настраиваемым тайм-аутом

• Проверка результатов с автоматическим повтором при пустых результатах

• Поддержка нескольких баз данных

Related MCP server: PostgreSQL MCP Server

Требования

• Python 3.11+

• PostgreSQL

• API-ключ OpenAI

Установка

pip install -e .

Для разработки:

pip install -e ".[dev]"

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

Скопируйте .env.example в .env и заполните свои значения:

cp .env.example .env

Пример для нескольких баз данных:

PG_MCP_DATABASES=postgresql://user:pass@host1:5432/db1,postgresql://user:pass@host2:5432/db2

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

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

{
  "mcpServers": {
    "pg-mcp": {
      "command": "pg-mcp",
      "args": [],
      "env": {
        "PG_MCP_DATABASES": "postgresql://user:pass@localhost:5432/mydb",
        "OPENAI_API_KEY": "sk-...",
        "PG_MCP_SCHEMA_CACHE_PATH": "~/.cache/pg-mcp/schema.json"
      }
    }
  }
}

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

query

Запрос к базе данных на естественном языке.

{
  "question": "What are the top 10 customers by sales last month?",
  "database": "mydb",
  "return_sql": false,
  "max_rows": 100
}

• return_sql: true — возвращает сгенерированный SQL без выполнения

• return_sql: false (по умолчанию) — выполняет и возвращает результаты

list_databases

Список всех доступных баз данных со сводной информацией.

describe_database

Получение подробной информации о схеме базы данных.

{
  "database": "mydb",
  "schema": "public",
  "pattern": "user"
}

refresh_schema

Обновление кэша схемы из базы данных.

{
  "database": "mydb"
}

Опустите database, чтобы обновить все базы данных.

Тестирование с фикстурами баз данных

Директория fixtures/ содержит три готовые базы данных для локального тестирования.

Настройка

# From project root, create & seed all fixture databases
cd fixtures
make all

# Or create individual ones
make small     # pg_mcp_test_small  — bookshelf (4 tables, ~50 rows)
make medium    # pg_mcp_test_medium — ecommerce (12 tables, ~500 rows)
make large     # pg_mcp_test_large  — enterprise (28 tables, ~5000 rows)

Переопределите учетные данные PostgreSQL через переменные окружения (по умолчанию: root / admin123 @ localhost:5432):

make all PGUSER=myuser PGPASSWORD=mypass PGHOST=127.0.0.1

Настройка .env

Укажите PG_MCP_DATABASES на базы данных из фикстур:

PG_MCP_DATABASES=postgresql://root:admin123@localhost:5432/pg_mcp_test_small,postgresql://root:admin123@localhost:5432/pg_mcp_test_medium,postgresql://root:admin123@localhost:5432/pg_mcp_test_large

Тестирование с помощью MCP Inspector

Используйте встроенный инспектор MCP для интерактивного тестирования:

cd /path/to/postgres-mcp
fastmcp dev src/pg_mcp/server.py:mcp

Это откроет UI в браузере, где вы сможете напрямую вызывать инструменты, такие как query, list_databases и describe_database.

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

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

{
  "mcpServers": {
    "pg-mcp": {
      "command": "python3",
      "args": ["-m", "pg_mcp.server"],
      "cwd": "/path/to/postgres-mcp"
    }
  }
}

Примечание: При использовании cwd сервер считывает .env из этой директории. Вы также можете передать переменные окружения через ключ "env".

Тестовые запросы

После подключения попробуйте выполнить эти запросы на естественном языке к базам данных из фикстур:

Очистка

cd fixtures
make drop-all      # Remove all fixture databases
make refresh-all   # Drop + recreate + re-seed

Запуск тестов

python3 -m pytest tests/ -v

Как это работает

User question
  → Schema context assembled from cache
  → OpenAI generates SQL
  → Safety validation (SELECT-only, no dangerous functions, LIMIT injection)
  → Execute in read-only transaction with timeout
  → Optional result validation on empty results
  → Return SQL or query results

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

• Сгенерированный SQL проверяется на выполнение только операций SELECT (включая проверки CTE)

• Заблокировано более 40 опасных функций PostgreSQL (управление сессиями, консультативные блокировки, dblink, доступ к файловой системе, изменение последовательностей и т.д.)

• Все запросы выполняются в транзакциях только для чтения

• Автоматическое ограничение LIMIT предотвращает получение больших наборов данных

• Тайм-аут запроса предотвращает выполнение длительных операций

• Пароли для подключения никогда не отображаются в логах или ответах API