database-mcp

SQL MCP сервер для баз данных с настоящей постраничной выдачей результатов на стороне сервера — функция, которой нет ни у одного устоявшегося MCP сервера для баз данных (DBHub ограничивает количество строк, Google's MCP Toolbox возвращает всё, mcp-alchemy обрезает на 4000 символов).

Эталонная реализация для PostgreSQL.

Зачем

Каждый существующий SQL MCP сервер либо обрезает большие результаты, либо сбрасывает их целиком в контекст модели. Спецификация MCP поддерживает пагинацию только для операций list (tools/list), но не для результатов инструментов. database-mcp закрывает этот пробел:

• Запрос выполняется один раз как серверный курсор PostgreSQL (DECLARE/FETCH FORWARD) внутри удерживаемой транзакции.

• Каждый fetch(cursor) продолжает ровно с того места, где закончилась последняя страница — без повторного выполнения, без повторного сканирования OFFSET, а снимок MVCC сохраняет результат стабильным даже при конкурентных записях.

• Страницы ограничены количеством строк (page_size) и размером в байтах (max_page_bytes); слишком большие ячейки обрезаются с явным маркером.

• Удерживаемые курсоры ограничены: максимум N одновременных (вытеснение LRU), вытеснение по TTL простоя, плюс idle_in_transaction_session_timeout как серверная страховка. Исчерпанные курсоры закрываются автоматически.

Related MCP server: pgsql-mcp

Профили подключения — управляются ИИ в рантайме

Подключения — это именованные профили, сохраняемые в ~/.config/database-mcp/profiles.json (chmod 600). ИИ может добавлять, изменять, тестировать и удалять их на лету через инструменты — без перезапуска сервера:

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• каждый инструмент запроса принимает необязательный параметр profile; при его отсутствии используется профиль по умолчанию.

Профили по умолчанию доступны только для чтения (сессионный default_transaction_read_only); запись требует явного профиля с allow_writes=true.

SSH-мост

Профиль может получить доступ к базе данных, доступной только через SSH (классическая схема «Postgres слушает localhost на удалённом хосте»):

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• Туннель — это подпроцесс системного ssh (-N -L, BatchMode, keepalives) — ваш ~/.ssh/config, ключи и агент применяются без изменений. Аутентификация должна работать без интерактивного ввода.

• ssh_remote_host/ssh_remote_port по умолчанию соответствуют хосту/порту DSN, видимому с SSH-хоста; если хост DSN совпадает с SSH-хостом, по умолчанию используется 127.0.0.1 (обычный случай).

• Туннели запускаются лениво, проверяются на каждом использовании и автоматически пересоздаются. Если туннель умирает во время пагинации, его курсоры инвалидируются с понятной ошибкой, а следующий запрос переподключается.

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

Инструменты

Результаты — компактный JSON: колонки один раз, строки как массивы — примерно вдвое меньше токенов, чем формат «строка-словарь», который используют другие серверы. query также возвращает estimated_rows (оценка планировщика через EXPLAIN), чтобы модель знала, с чем она работает при пагинации.

Установка и запуск

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Регистрация в Claude Code:

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

Опции: --profiles FILE, --allow-writes, --page-size 50, --max-page-size 500, --max-page-bytes 32000, --max-cell 400, --cursor-ttl 300, --max-cursors 4, --statement-timeout 30, --keepalive 120, --connect-timeout 5. Переменные окружения: DATABASE_MCP_DSN / DATABASE_URL, DATABASE_MCP_PROFILES.

Обработка устаревших соединений

Мёртвые соединения обнаруживаются быстро на каждом уровне, а не зависают:

• SSH-туннели: ServerAliveInterval = --keepalive (по умолчанию 2 мин) с ServerAliveCountMax=1 — один пропущенный пробный пакет завершает процесс туннеля, который менеджер движка обнаруживает при следующем использовании и лениво пересоздаёт.

• Соединения с БД: TCP keepalives (keepalives_idle = --keepalive, пробы каждые 10 с, 3 пропуска) ловят мёртвых пиров за ~30 с — включая закреплённые курсорные соединения вне пула.

• Проверка при выдаче из пула: каждое выдаваемое соединение проверяется дешёвым round-trip; устаревшее отбрасывается и прозрачно заменяется — вызывающий никогда не видит ошибку. Простаивающие соединения в пуле перерабатываются через --keepalive секунд; попытки подключения завершаются ошибкой через --connect-timeout (по умолчанию 5 с) вместо стандартных ~2 мин TCP.

Тесты

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

Лицензия

MIT