db-mcp-server

Локальный MCP-сервер, который предоставляет ИИ-ассистенту для программирования (например, Claude Code) изолированный по учётным данным доступ к вашим базам данных PostgreSQL. Ассистент отправляет только SQL и получает только строки — имена пользователей баз данных, пароли и SSH-ключи никогда не попадают в контекст модели или в транскрипт разговора.

Зачем

Подключение ИИ-ассистента к базе данных обычно означает размещение строк подключения и паролей там, где модель (и её транскрипт) может их прочитать. Этот сервер сохраняет эту границу: он владеет зашифрованными учётными данными и SSH-туннелями, предоставляет небольшой набор инструментов только для SQL и по умолчанию работает в режиме только для чтения.

Related MCP server: Postgres Scout MCP

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

• Каталог (registry.yaml) — маршрутизация без секретов. Организован как customers → environments → services; каждая служба сопоставляется с именем базы данных и secret_ref (указателем в хранилище — никогда не учётными данными).

• Хранилище (vault.enc) — AES-256-GCM с ключом, полученным через scrypt. Содержит учётные данные БД, расшифровываемые в память один раз при запуске с помощью парольной фразы.

• Пул туннелей — один SSH-туннель на (customer, environment) через sshtunnel, привязанный к эфемерному порту 127.0.0.1.

• Исполнитель — psycopg. run_query выполняется в транзакции Postgres READ ONLY (движок отклоняет любую запись); run_write_query требует confirm=true.

Установка

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1   (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"

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

Конфигурация задаётся через переменные окружения; значения по умолчанию разрешаются относительно корня проекта.

Подготовка (первоначальная настройка)

1. Скопируйте шаблон и заполните реальными значениями:

cp bootstrap.example.yaml bootstrap.yaml

2. Поместите ваши SSH-приватные ключи в keys/ (имена файлов должны совпадать с полями pem_key в каталоге).

3. Сгенерируйте несекретный каталог и зашифрованное хранилище (запросит парольную фразу, которую вы будете использовать для запуска сервера):

python -m db_mcp_server.bootstrap --dry-run   # preview, writes nothing
python -m db_mcp_server.bootstrap             # writes registry.yaml + vault.enc
python -m db_mcp_server.vault_admin verify     # expect {"ok": true}

bootstrap.yaml содержит учётные данные в открытом виде — он игнорируется git; удалите его или храните офлайн после создания хранилища.

Инструменты командной строки

(Консольные команды доступны после pip install -e .; форма python -m db_mcp_server.<module> работает всегда.)

Инструменты, доступные ассистенту

• list_databases() — каталог (customers → environments → services); без секретов.

• run_query(customer, environment, service, sql, max_rows?) — только чтение.

• run_write_query(customer, environment, service, sql, confirm) — запись с подтверждением.

Ошибки предметной области возвращаются в виде структурированного {error_code, message}, а не исключения, чтобы ассистент мог на них реагировать.

Регистрация в MCP-клиенте

Пример .mcp.json (скорректируйте пути). Используйте ${DB_MCP_PASSPHRASE}, чтобы парольная фраза читалась из оболочки, а не была записана в файл:

{
  "mcpServers": {
    "db": {
      "command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "db_mcp_server.server"],
      "env": {
        "DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
      }
    }
  }
}

Замечания по безопасности

• vault.enc, keys/, bootstrap.yaml, *.env и *.pem игнорируются git — никогда не коммитьте их.

• Парольная фраза хранилища передаётся через DB_MCP_PASSPHRASE (или запрос) — никогда не хранится в registry.yaml, argv или журналах.

• db-vault читает пароль БД через скрытый запрос (getpass), никогда через argv.

• run_query доступен только для чтения на уровне движка Postgres; записи требуют confirm=true.

Тесты

pip install -e ".[dev]" && python -m pytest -q

Интеграционный тест БД пропускается, если DB_MCP_TEST_DSN не указывает на доступный PostgreSQL.

Дорожная карта (не в этой сборке)

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