MCP Toolbox for Databases — Установка & Живое демо

Зачем использовать

Ключевые функции

Один бинарник, много движков: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
Декларативный tools.yaml — каждый инструмент это именованный параметризованный запрос, а не произвольный SQL
Готовые конфиги (--prebuilt postgres) для мгновального использования без настройки
Пул соединений и auth (IAM, OAuth, API key) управляются централизованно, а не через prompt
Транспорт Stdio или HTTP/SSE — работает с Claude Desktop, Cursor, Codex, IDE, кастомными агентами
Правила авторизации на уровне инструмента — можно ограничить вызов деструктивных операций

Живое демо

Как выглядит на практике

mcp-toolbox-databases.replay ▶ готово

0/0

Установка

Выберите клиент

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Откройте Claude Desktop → Settings → Developer → Edit Config. Перезапустите после сохранения.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Щёлкните значок MCP Servers на боковой панели Cline, затем "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Тот же формат, что и Claude Desktop. Перезапустите Windsurf для применения.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue использует массив объектов серверов, а не map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

Добавьте в context_servers. Zed перезагружается автоматически.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

Однострочная команда. Проверить: claude mcp list. Удалить: claude mcp remove.

Сценарии использования

Реальные сценарии: MCP Toolbox for Databases

Как дать Claude безопасный read-only доступ к production Postgres

👤 Backend / data-инженеры, которым нужна LLM-аналитика без риска утечки данных ⏱ ~25 min intermediate

Когда использовать: Хочется, чтобы Claude отвечал на вопросы по реальной базе без универсального инструмента execute_sql, который может выполнить DROP TABLE.

Предварительные требования

Postgres, доступный через libpq URL — Использовать роль только на чтение; никогда — записываемого пользователя приложения
Docker или Go — Toolbox поставляется как единый бинарник; Docker-образ проще всего

Поток

Запустить Toolbox с профилем postgres

Запусти mcp-toolbox в режиме stdio с флагом --prebuilt postgres и POSTGRES_URL, указывающим на read-реплику.✓ Скопировано

→ Toolbox логирует tools registered: list_tables, describe_table, execute_sql_readonly
Подключить к Claude Desktop

Добавь docker-конфиг toolbox в claude_desktop_config.json в раздел mcpServers, затем перезапусти Claude.✓ Скопировано

→ Команда /mcp показывает инструменты toolbox без ошибок
Задать реальный вопрос

Toolbox: покажи таблицы. Для orders — какова медиана заказа за последние 7 дней? Покажи точный SQL.✓ Скопировано

→ Claude вызывает list_tables → describe_table → execute_sql_readonly с SELECT (без UPDATE/DELETE)

Итог: Read-only аналитика по реальным данным без риска мутации, с логом каждого запроса.

Подводные камни

Указан записываемый пользователь — Claude в итоге вызывает мутирующий инструмент — Всегда используй роль только с GRANT SELECT; проверяй через \du в psql
Пул соединений исчерпан при параллельных вызовах агента — Установи pool.max_open_conns в tools.yaml; значение по умолчанию консервативное

Сочетать с: filesystem · github

Создать аналитический инструмент с валидацией параметров вручную

👤 Команды, которые хотят не сырой SQL, а только одобренные запросы ⏱ ~20 min intermediate

Когда использовать: Хочется, чтобы Claude отвечал «топ-10 клиентов этого месяца», но не изобретал свои JOIN-ы.

Предварительные требования

Файл tools.yaml — Создай по пути ~/.mcp-toolbox/tools.yaml

Поток

Написать параметризованный инструмент

Добавь инструмент top_customers в tools.yaml: параметр since: date, запрос SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Скопировано

→ Toolbox перезагружается и открывает только top_customers — без execute_sql_readonly
Вызвать из Claude

Используй top_customers since=2026-04-01 и объясни результат.✓ Скопировано

→ Единственный вызов инструмента с валидированным date-параметром и отформатированный результат

Итог: Закрытый аналитический интерфейс — Claude не может запустить ничего, что не было объявлено.

Подводные камни

Забыл убрать prebuilt-инструмент execute_sql — Убери --prebuilt; загружай только свой tools.yaml

Исследовать датасеты BigQuery без написания SQL

👤 Аналитики в Google Cloud ⏱ ~20 min intermediate

Когда использовать: Есть BigQuery-проект и хочется, чтобы Claude отвечал на вопросы с контролем стоимости запросов.

Предварительные требования

GCP-проект + датасет — Запусти gcloud auth application-default login, чтобы Toolbox подхватил credentials

Поток

Запустить Toolbox с --prebuilt bigquery

Запусти toolbox --prebuilt bigquery с PROJECT=my-proj.✓ Скопировано

→ Зарегистрированы инструменты bq_list_datasets, bq_dry_run, bq_query
Всегда сначала делать dry-run

Перед выполнением любого запроса вызови bq_dry_run для оценки сканируемых байт. Если > 1 ГБ — спроси меня перед выполнением.✓ Скопировано

→ Оценка стоимости показана до платного запроса

Итог: Ответы BigQuery с контролем стоимости — никаких неожиданных запросов за $200.

Подводные камни

Несоответствие региона по умолчанию (US vs EU) — Установи переменную окружения BIGQUERY_LOCATION

Запрашивать несколько баз данных из одной сессии Claude

👤 Инженеры, отлаживающие проблемы между хранилищами ⏱ ~30 min advanced

Когда использовать: Данные заказов в Postgres, события в BigQuery, кеш в Redis — нужна корреляция по всем трём.

Предварительные требования

tools.yaml с несколькими источниками — Опиши каждый источник в разделе sources: и привяжи к нему инструменты

Поток

Подключить все три источника

Добавь postgres-prod, bq-events, redis-cache как источники в tools.yaml. Добавь по 1–2 инструмента на каждый.✓ Скопировано

→ Toolbox запускается, все источники помечены как healthy
Задать cross-store вопрос

По заказу 12345: получи строку из Postgres, таймлайн событий из BigQuery и текущее состояние кеша из Redis. Сопоставь данные.✓ Скопировано

→ Три параллельных вызова инструментов, единый связный ответ

Итог: Отладка между хранилищами без трёх отдельных инструментов или SSH-сессий.

Подводные камни

Проверка работоспособности источника падает молча — Запусти toolbox validate tools.yaml перед стартом

Сочетать с: filesystem

Комбинации

Сочетайте с другими MCP — эффект x10

mcp-toolbox-databases + filesystem

Получить результат запроса и записать его в CSV в рабочем пространстве

Toolbox: топ-100 заказов за эту неделю. Filesystem: сохранить как /tmp/orders.csv.✓ Скопировано

mcp-toolbox-databases + github

Открыть PR с SQL-миграцией после того как Claude предложил изменение схемы

Toolbox: опиши таблицу orders. GitHub: открой PR с добавлением индекса на customer_id.✓ Скопировано

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать	Стоимость
list_tables	schema?: str	Первый шаг исследования	1 запрос
describe_table	table: str	Перед написанием SQL к незнакомой таблице	1 запрос
execute_sql_readonly	sql: str	Произвольная аналитика по read-реплике	1 запрос
bq_dry_run	sql: str	BigQuery: всегда перед bq_query	бесплатно (dry run)
bq_query	sql: str	После того как dry run показал приемлемую стоимость	платно, по объёму сканируемых байт
<your-custom-tool>	зависит от tools.yaml	Всё, что объявлено в tools.yaml	1 запрос

Стоимость и лимиты

Во что обходится

Квота API: Нет — ограничено лимитом соединений вашей БД
Токенов на вызов: 100–5000 в зависимости от размера результата
Деньги: Бесплатный OSS; базовая БД и облако тарифицируются обычным образом
Совет: Ограничь количество строк в tools.yaml (например, LIMIT 200); для BigQuery всегда используй bq_dry_run первым

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

Права, секреты, радиус поражения

Минимальные скоупы: роль БД только на чтение

Хранение учётных данных: Переменные окружения или Google ADC; Toolbox не хранит credentials постоянно

Исходящий трафик: Прямое подключение к БД — без промежуточных третьих сторон. Toolbox работает только локально.

Никогда не давайте: DBA DROP/TRUNCATE в production

Всегда ставь перед production read-реплику с ролью только на чтение; никогда — записываемого пользователя приложения

Устранение неполадок

Частые ошибки и исправления

connection refused / пул соединений исчерпан

Увеличь pool.max_open_conns в tools.yaml; проверь лимит соединений БД

Проверить: psql, выполни SELECT count(*) FROM pg_stat_activity

инструмент не найден

При использовании --prebuilt имя инструмента, например, pg_list_tables; проверь через toolbox list-tools

BigQuery 403 access denied

Запусти gcloud auth application-default login и выдай roles/bigquery.dataViewer

Проверить: bq ls

Ошибки Spanner Cloud SDK

Укажи GOOGLE_APPLICATION_CREDENTIALS на JSON сервисного аккаунта

Альтернативы

MCP Toolbox for Databases в сравнении

Альтернатива	Когда использовать	Компромисс
DBHub	Нужен один бинарник без зависимостей для Postgres/MySQL/SQL Server	Меньше поддержки BigQuery/Spanner, нет Google IAM
Postgres MCP (modelcontextprotocol)	Только Postgres, без YAML-конфигурации	Менее строгий — по умолчанию открывает execute_sql
MySQL MCP (benborla)	Только MySQL, только чтение	Один движок, проще

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills