Berth -- MCP-сервер для баз данных

License: MIT

Безопасная гавань для ваших данных — доступ к базам данных для ИИ-инструментов.

Berth — это сервер Model Context Protocol, который предоставляет ИИ-ассистентам безопасный и структурированный доступ к базам данных PostgreSQL, SQLite и MySQL. Он предоставляет 13 инструментов для проверки схем, выполнения запросов, управления данными, генерации миграций и выполнения резервного копирования — всё это регулируется трехуровневой моделью безопасности, предотвращающей случайное повреждение данных.

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

Berth поддерживает три режима работы, которые контролируют допустимость SQL-команд:

Режим	По умолчанию	Разрешает	Блокирует
read-only	Да	`SELECT`, `EXPLAIN`	Все операции записи
write	Нет	`INSERT`, `UPDATE`, `DELETE`, `CREATE`	`DROP`, `TRUNCATE`, `ALTER DROP`, `DELETE` без `WHERE`
admin	Нет	Всё	Деструктивные операции требуют токен подтверждения (срок действия 60 с)

Сервер запускается в режиме read-only. Режимы записи и администратора должны быть явно включены. Деструктивные операции в режиме администратора генерируют одноразовый токен подтверждения, который истекает через 60 секунд — ИИ должен повторить токен, чтобы подтвердить намерение.

Инструменты

Инструмент	Описание	Ключевые параметры
`health`	Проверка работоспособности сервера	--
`db_connect`	Подключение к базе данных	`dsn` (строка подключения)
`db_query`	Выполнение SELECT-запроса (автоматически добавляет LIMIT 1000)	`connection_id`, `sql`
`db_execute`	Выполнение INSERT/UPDATE/DELETE (соблюдает режим безопасности)	`connection_id`, `sql`, `confirmation_token`
`db_schema`	Список таблиц, представлений и индексов	`connection_id`
`db_describe`	Детали столбцов таблицы	`connection_id`, `table`
`db_relationships`	Связи внешних ключей	`connection_id`, `table` (опционально)
`db_size`	Размеры базы данных и таблиц	`connection_id`
`db_active_queries`	Текущие выполняемые запросы (только PostgreSQL)	`connection_id`
`db_explain`	Запуск EXPLAIN ANALYZE для запроса	`connection_id`, `sql`
`generate_migration`	Генерация SQL-миграции путем сравнения схем	`connection_id` + `target_sql` или `from_connection` + `to_connection`
`db_backup`	Создание резервной копии базы данных	`connection_id`, `output_path`
`db_restore`	Восстановление из резервной копии (режим admin + токен подтверждения)	`connection_id`, `input_path`, `confirmation_token`

Миграции схем

Инструмент generate_migration сравнивает две схемы и создает SQL-код, учитывающий диалект, для миграции от одной к другой. Доступны два режима работы:

Режим 1 — Живая база данных против целевого DDL:

Укажите connection_id (активное подключение) и target_sql (инструкции CREATE TABLE, описывающие желаемую схему). Berth анализирует живую базу данных и сравнивает её с разобранным целевым кодом.

Режим 2 — Две живые базы данных:

Укажите from_connection и to_connection (два активных ID подключения). Berth анализирует обе базы и генерирует миграцию для преобразования источника в целевую схему.

Что генерируется:

CREATE TABLE для новых таблиц
ALTER TABLE ADD COLUMN для новых столбцов
ALTER TABLE ALTER COLUMN / MODIFY COLUMN для изменений типа, возможности хранения NULL и значений по умолчанию
CREATE INDEX / DROP INDEX для изменений индексов
ADD CONSTRAINT / DROP CONSTRAINT для изменений внешних ключей
DROP TABLE и DROP COLUMN комментируются с предупреждениями (безопасность прежде всего)

Обработка диалектов:

PostgreSQL -- использует ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT
MySQL -- использует MODIFY COLUMN для всех изменений столбцов, DROP INDEX ... ON table
SQLite -- предупреждает о неподдерживаемых операциях и включает шаблон перестройки таблицы для изменений, требующих этого (ALTER COLUMN, DROP COLUMN в старых версиях, изменения ограничений)

Поддерживаемые базы данных

PostgreSQL -- полная поддержка, включая pg_stat_activity, EXPLAIN ANALYZE, резервное копирование/восстановление через pg_dump/psql
SQLite -- полная поддержка, включая интроспекцию PRAGMA, .backup/.restore через CLI sqlite3
MySQL -- полная поддержка, включая интроспекцию information_schema, резервное копирование/восстановление через mysqldump/mysql

Установка

Из PyPI:

pip install berth-mcp

Или в изолированной среде:

pipx install berth-mcp

Поддержка MySQL требует дополнительной зависимости:

pip install berth-mcp[mysql]

Драйверы PostgreSQL (asyncpg) и SQLite (aiosqlite) включены по умолчанию.

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

Запуск сервера:

berth

Berth общается через stdio с использованием протокола MCP. Он предназначен для запуска клиентом MCP, а не для автономной работы.

Claude Code

claude mcp add berth -- berth

Claude Desktop

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

{
  "mcpServers": {
    "berth": {
      "command": "berth",
      "args": []
    }
  }
}

Если установлено в виртуальной среде, используйте полный путь:

{
  "mcpServers": {
    "berth": {
      "command": "/path/to/venv/bin/berth",
      "args": []
    }
  }
}

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

Переменная	По умолчанию	Описание
`BERTH_BACKUP_DIR`	Текущая рабочая директория	Директория-песочница для путей резервного копирования и восстановления. Все пути проверяются на нахождение внутри этой директории.

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

Трехуровневая модель безопасности -- по умолчанию только чтение, запись требует явного подтверждения, деструктивные операции требуют токенов подтверждения
Токены подтверждения -- одноразовые UUID со сроком действия 60 секунд для DROP, TRUNCATE, ALTER DROP и удаления всей таблицы (DELETE)
Защита от SQL-инъекций -- имена таблиц проверяются по sqlite_master перед использованием в операторах PRAGMA; везде используются параметризованные запросы
Защита от обхода путей (path traversal) -- пути резервного копирования/восстановления разрешаются и проверяются на нахождение внутри BERTH_BACKUP_DIR; нулевые байты отклоняются
Маскирование паролей -- пароли DSN маскируются во всех выходных данных и сообщениях об ошибках

Разработка

git clone https://github.com/seayniclabs/berth.git
cd berth
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -q

Интеграционные тесты для PostgreSQL и MySQL требуют Docker:

docker compose -f tests/docker-compose.test.yml up -d
python -m pytest tests/ -q
docker compose -f tests/docker-compose.test.yml down

Лицензия

MIT

Berth