MCP-сервер PostgreSQL

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

Версия 0.2.0

Функции

Сервер предоставляет следующие инструменты:

1. Анализ и настройка базы данных

1.1. Анализ базы данных ( `analyze_database` )

Анализирует конфигурацию базы данных PostgreSQL и показатели производительности:

Анализ конфигурации
Показатели производительности
Оценка безопасности
Рекомендации по оптимизации

// Example usage
{
  "analysisType": "performance" // Optional: "configuration" | "performance" | "security"
}

1.2. Получить инструкции по настройке ( `get_setup_instructions` )

Предоставляет пошаговые инструкции по установке и настройке PostgreSQL:

Шаги установки для конкретной платформы
Рекомендации по конфигурации
Лучшие практики безопасности
Задачи после установки

// Example usage
{
  "platform": "linux", // Required: "linux" | "macos" | "windows"
  "version": "15", // Optional: PostgreSQL version
  "useCase": "production" // Optional: "development" | "production"
}

1.3. Отладочная база данных ( `debug_database` )

Устранение распространенных проблем PostgreSQL:

Проблемы с подключением
Узкие места производительности
Блокировка конфликтов
Статус репликации

// Example usage
{
  "issue": "performance", // Required: "connection" | "performance" | "locks" | "replication"
  "logLevel": "debug" // Optional: "info" | "debug" | "trace"
}

2. Управление схемой

2.1. Получить информацию о схеме ( `get_schema_info` )

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

Список таблиц в базе данных
Определения столбцов
Ограничения (первичные ключи, внешние ключи и т. д.)
Индексы

// Example usage
{
  "tableName": "users" // Optional: specific table to get info for
}

2.2. Создать таблицу ( `create_table` )

Создайте новую таблицу с указанными столбцами:

Определите имена и типы столбцов
Установить ограничения, допускающие значение NULL
Установить значения по умолчанию

// Example usage
{
  "tableName": "users", // Required
  "columns": [ // Required
    { "name": "id", "type": "SERIAL", "nullable": false },
    { "name": "username", "type": "VARCHAR(100)", "nullable": false },
    { "name": "email", "type": "VARCHAR(255)", "nullable": false },
    { "name": "created_at", "type": "TIMESTAMP", "default": "NOW()" }
  ]
}

2.3. Изменить таблицу ( `alter_table` )

Изменить существующие таблицы:

Добавить новые столбцы
Изменить типы столбцов или ограничения
Удалить столбцы

// Example usage
{
  "tableName": "users", // Required
  "operations": [ // Required
    { "type": "add", "columnName": "last_login", "dataType": "TIMESTAMP" },
    { "type": "alter", "columnName": "email", "nullable": false },
    { "type": "drop", "columnName": "temporary_field" }
  ]
}

2.4. Получить перечисления ( `get_enums` )

Получите информацию о типах ENUM PostgreSQL.

// Example usage
{
  "schema": "public", // Optional
  "enumName": "user_status" // Optional
}

2.5. Создать перечисление ( `create_enum` )

Создайте новый тип ENUM в базе данных.

// Example usage
{
  "enumName": "order_status", // Required
  "values": ["pending", "processing", "shipped", "delivered"], // Required
  "schema": "public", // Optional
  "ifNotExists": true // Optional
}

3. Миграция данных

3.1. Экспорт данных таблицы ( `export_table_data` )

Экспорт данных таблицы в формат JSON или CSV:

Фильтрация данных с помощью предложения WHERE
Ограничить количество строк
Выберите выходной формат

// Example usage
{
  "tableName": "users", // Required
  "outputPath": "./exports/users.json", // Required
  "where": "created_at > '2023-01-01'", // Optional
  "limit": 1000, // Optional
  "format": "json" // Optional: "json" | "csv"
}

3.2 Импорт данных таблицы ( `import_table_data` )

Импорт данных из файлов JSON или CSV:

При желании можно обрезать таблицу перед импортом
Поддержка разных форматов
Пользовательские разделители CSV

// Example usage
{
  "tableName": "users", // Required
  "inputPath": "./imports/users.json", // Required
  "truncateFirst": false, // Optional
  "format": "json", // Optional: "json" | "csv"
  "delimiter": "," // Optional: for CSV files
}

3.3 Копирование между базами данных ( `copy_between_databases` )

Копирование данных между двумя базами данных PostgreSQL:

Фильтрация данных с помощью предложения WHERE
При желании можно обрезать целевую таблицу

// Example usage
{
  "sourceConnectionString": "postgresql://user:password@localhost:5432/source_db", // Required
  "targetConnectionString": "postgresql://user:password@localhost:5432/target_db", // Required
  "tableName": "users", // Required
  "where": "active = true", // Optional
  "truncateTarget": false // Optional
}

4. Мониторинг

4.1. База данных монитора ( `monitor_database` )

Мониторинг базы данных PostgreSQL в реальном времени:

Показатели базы данных (подключения, коэффициент попадания в кэш и т. д.)
Метрики таблиц (размер, количество строк, мертвые кортежи)
Активная информация о запросе
Блокировка информации
Статус репликации
Настраиваемые оповещения

// Example usage
{
  "includeTables": true, // Optional
  "includeQueries": true, // Optional
  "includeLocks": true, // Optional
  "includeReplication": false, // Optional
  "alertThresholds": { // Optional
    "connectionPercentage": 80,
    "longRunningQuerySeconds": 30,
    "cacheHitRatio": 0.95,
    "deadTuplesPercentage": 10,
    "vacuumAge": 7
  }
}

5. Функции

5.1. Получить функции ( `get_functions` )

Получите информацию о функциях PostgreSQL.

// Example usage
{
  "functionName": "calculate_total", // Optional
  "schema": "public" // Optional
}

5.2. Создать функцию ( `create_function` )

Создайте или замените функцию PostgreSQL.

// Example usage
{
  "functionName": "get_user_count", // Required
  "parameters": "", // Required (empty if no params)
  "returnType": "integer", // Required
  "functionBody": "SELECT count(*) FROM users;", // Required
  "language": "sql", // Optional
  "volatility": "STABLE", // Optional
  "schema": "public", // Optional
  "security": "INVOKER", // Optional
  "replace": true // Optional
}

5.3. Функция сброса ( `drop_function` )

Удалить функцию PostgreSQL.

// Example usage
{
  "functionName": "old_function", // Required
  "parameters": "integer", // Optional: required for overloaded functions
  "schema": "public", // Optional
  "ifExists": true, // Optional
  "cascade": false // Optional
}

6. Безопасность на уровне строк (RLS)

6.1. Включить RLS ( `enable_rls` )

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

// Example usage
{
  "tableName": "sensitive_data", // Required
  "schema": "secure" // Optional
}

6.2. Отключить RLS ( `disable_rls` )

Отключите безопасность на уровне строк для таблицы.

// Example usage
{
  "tableName": "sensitive_data", // Required
  "schema": "secure" // Optional
}

6.3. Создать политику RLS ( `create_rls_policy` )

Создайте политику безопасности на уровне строк.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "user_can_see_own_docs", // Required
  "using": "owner_id = current_user_id()", // Required
  "check": "owner_id = current_user_id()", // Optional
  "schema": "public", // Optional
  "command": "SELECT", // Optional
  "role": "app_user", // Optional
  "replace": false // Optional
}

6.4. Редактировать политику RLS ( `edit_rls_policy` )

Отредактируйте существующую политику безопасности на уровне строк.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "user_can_see_own_docs", // Required
  "schema": "public", // Optional
  "roles": ["app_user", "admin_user"], // Optional: New roles (empty or omit to keep existing/use default)
  "using": "owner_id = current_user_id() OR is_admin(current_user_id())", // Optional: New USING expression
  "check": "owner_id = current_user_id()" // Optional: New WITH CHECK expression
}

6.5. Отменить политику RLS ( `drop_rls_policy` )

Отмените политику безопасности на уровне строк.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "old_policy", // Required
  "schema": "public", // Optional
  "ifExists": true // Optional
}

6.6. Получить политики RLS ( `get_rls_policies` )

Получите политики безопасности на уровне строк.

// Example usage
{
  "tableName": "documents", // Optional
  "schema": "public" // Optional
}

7. Триггеры

7.1. Получить триггеры ( `get_triggers` )

Получите информацию о триггерах PostgreSQL.

// Example usage
{
  "tableName": "audit_log", // Optional
  "schema": "public" // Optional
}

7.2. Создать триггер ( `create_trigger` )

Создайте триггер PostgreSQL.

// Example usage
{
  "triggerName": "log_user_update", // Required
  "tableName": "users", // Required
  "functionName": "audit_user_change", // Required
  "schema": "public", // Optional
  "timing": "AFTER", // Optional
  "events": ["UPDATE"], // Optional
  "when": "OLD.email IS DISTINCT FROM NEW.email", // Optional
  "forEach": "ROW", // Optional
  "replace": false // Optional
}

7.3. Триггер сброса ( `drop_trigger` )

Удалить триггер PostgreSQL.

// Example usage
{
  "triggerName": "old_trigger", // Required
  "tableName": "users", // Required
  "schema": "public", // Optional
  "ifExists": true, // Optional
  "cascade": false // Optional
}

7.4. Установить состояние триггера ( `set_trigger_state` )

Включить или отключить триггер PostgreSQL.

// Example usage
{
  "triggerName": "log_user_update", // Required
  "tableName": "users", // Required
  "enable": false, // Required: true to enable, false to disable
  "schema": "public" // Optional
}

Предпосылки

Node.js >= 18.0.0
Сервер PostgreSQL (для операций с целевой базой данных)
Сетевой доступ к целевым экземплярам PostgreSQL

Установка

Установка через Smithery

Чтобы автоматически установить postgresql-mcp-server для Claude Desktop через Smithery :

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Ручная установка

Клонировать репозиторий
Установить зависимости:
npm install
Сборка сервера:
npm run build
Добавьте в файл настроек MCP (например, в настройки вашей IDE или глобальную конфигурацию MCP):Существует несколько способов настройки строки подключения к серверу в следующем порядке приоритета:
1. Аргумент, специфичный для инструмента : если при вызове определенного инструмента в аргументах непосредственно указывается connectionString , это значение будет использоваться для этого вызова.
2. Аргумент CLI : вы можете указать строку подключения по умолчанию при запуске сервера с помощью аргумента -cs или --connection-string .
3. Переменная среды : если ни одно из вышеперечисленного не указано, сервер будет искать переменную среды POSTGRES_CONNECTION_STRING .
Если строка подключения не найдена ни одним из этих методов, инструменты, требующие подключения к базе данных, не будут работать.
Пример использования аргумента CLI в настройках MCP:
{ "mcpServers": { "postgresql-mcp": { "command": "node", "args": [ "/path/to/postgresql-mcp-server/build/index.js", "--connection-string", "postgresql://username:password@server:port/dbname" // Optionally, add "--tools-config", "/path/to/your/mcp-tools.json" ], "disabled": false, "alwaysAllow": [] // Note: 'env' block for POSTGRES_CONNECTION_STRING can still be used as a fallback // if --connection-string is not provided in args. } } }
Пример использования переменной среды (если не используется аргумент CLI):
{ "mcpServers": { "postgresql-mcp": { "command": "node", "args": [ "/path/to/postgresql-mcp-server/build/index.js" // Optionally, add "--tools-config", "/path/to/your/mcp-tools.json" ], "disabled": false, "alwaysAllow": [], "env": { "POSTGRES_CONNECTION_STRING": "postgresql://username:password@server:port/dbname" } } } }
Использование аргумента CLI --connection-string или переменной среды POSTGRES_CONNECTION_STRING делает аргумент connectionString необязательным для большинства вызовов инструментов.

Конфигурация инструмента

Сервер поддерживает фильтрацию инструментов, включаемых через внешний файл конфигурации JSON.

Параметр CLI : используйте -tc <path> или --tools-config <path> чтобы указать путь к файлу конфигурации инструментов.
Формат файла : Файл JSON должен содержать объект с ключом enabledTools , который содержит массив строк названий инструментов.Пример mcp-tools.json :
{ "enabledTools": [ "get_schema_info", "analyze_database", "export_table_data" ] }
Поведение :
- Если файл конфигурации предоставлен и действителен, будут включены только перечисленные инструменты.
- Если файл не предоставлен, недействителен или не может быть прочитан, все инструменты будут включены по умолчанию.
- Сервер будет регистрировать, какие инструменты включены на основе этой конфигурации.

Разработка

npm run dev — запуск сервера разработки с горячей перезагрузкой
npm run lint — Запустить ESLint
npm test — запуск тестов (если настроен)

Соображения безопасности

Безопасность соединения
- Сервер определяет строку подключения к базе данных на основе следующего приоритета:
  1. connectionString указывается непосредственно в аргументах инструмента.
  2. --connection-string Аргумент CLI, используемый при запуске сервера.
  3. Переменная среды POSTGRES_CONNECTION_STRING .
- Убедитесь, что строки подключения (особенно содержащие учетные данные) управляются безопасно.
- Использует пул соединений через pg (ранее @vercel/postgres ).
- Проверяет строки подключения.
- Поддерживает соединения SSL/TLS (настройка через строку подключения).
Безопасность запроса
- Выполняет предопределенные операции; по возможности избегает произвольного выполнения SQL.
- Использует параметризованные запросы, где это применимо, для предотвращения SQL-инъекций.
- Регистрирует операции для аудита.
Аутентификация
- Использует механизмы аутентификации PostgreSQL через строку подключения.
- Безопасно управляйте учетными данными вашей базы данных. Не задавайте их в клиентских запросах, если это возможно; предпочитайте использовать параметр CLI --connection-string или переменную среды POSTGRES_CONNECTION_STRING при настройке сервера.

Лучшие практики

Настройте безопасную строку подключения к базе данных по умолчанию с помощью параметра CLI --connection-string или переменной среды POSTGRES_CONNECTION_STRING .
Если инструменту необходимо подключиться к базе данных, отличной от базы данных по умолчанию, укажите connectionString непосредственно в аргументах этого инструмента.
Всегда используйте безопасные строки подключения с надлежащими учетными данными, желательно настроенными с помощью переменной среды POSTGRES_CONNECTION_STRING .
Соблюдайте рекомендации по обеспечению безопасности производства для чувствительных сред.
Регулярно отслеживайте и анализируйте производительность базы данных с помощью инструмента monitor_database .
Поддерживайте версию PostgreSQL в актуальном состоянии.
Самостоятельно реализуйте надлежащие стратегии резервного копирования.
Используйте пул соединений для лучшего управления ресурсами (обрабатывается внутри).
Реализуйте правильную обработку ошибок и ведение журнала.
Регулярные проверки безопасности и обновления.

Обработка ошибок

Сервер реализует обработку ошибок для:

Сбои соединения
Ошибки запроса
Неверные входные данные
Проблемы с разрешениями

Ошибки возвращаются в стандартном формате ошибок MCP.

Внося вклад

Форк репозитория
Создать ветку функций
Примите ваши изменения
Нажмите на ветку
Создать запрос на извлечение

Лицензия

Данный проект лицензирован по лицензии AGPLv3 — подробности см. в файле LICENSE.

Integrations