MCP Toolbox for Databases (BigQuery)

Что умеет сервер

MCP Toolbox for Databases выпускает Google в организации googleapis, это открытый сервер под лицензией Apache 2.0. Репозиторий раньше назывался genai-toolbox и был переименован в mcp-toolbox. Один и тот же сервер умеет подключаться к разным базам, а здесь описан режим BigQuery: его включает флаг --prebuilt=bigquery, и клиент сразу получает готовый набор инструментов.

В этот набор входят список наборов данных и таблиц, метаданные наборов данных и таблиц, поиск по каталогу, выполнение произвольного SQL на GoogleSQL, прогноз временных рядов, анализ вклада факторов (key driver analysis) и инструмент ask_data_insights, который отвечает на вопросы о содержимом таблиц через Conversational Analytics API.

Когда использовать

Подключайте сервер, когда аналитику или разработчику нужно прямо из IDE или терминала разобраться в данных BigQuery: найти таблицы, посмотреть схему, проверить гипотезу запросом или построить прогноз. Режим BigQuery заточен под это, а если нужна своя логика, тот же сервер позволяет описать в файле tools.yaml собственные параметризованные запросы и отдать агенту только их.

В документации прямо сказано, что готовые конфигурации рассчитаны на этап разработки, когда агент помогает доверенному разработчику, и не годятся для рабочей среды, где с агентом могут говорить недоверенные пользователи.

Ограничения и безопасность

Права определяются теми учётными данными, под которыми запущен сервер. По умолчанию это Application Default Credentials, и у такой учётной записи должны быть нужные роли: для запросов нужна roles/bigquery.user, для просмотра всех наборов данных roles/bigquery.metadataViewer, для создания и изменения таблиц roles/bigquery.dataEditor, для разговорной аналитики roles/cloudaicompanion.user. Альтернатива: передавать сервису OAuth-токен самого пользователя, тогда запросы идут от его имени.

По умолчанию разрешены все запросы, поэтому для исследовательской работы стоит включить защиту. Переменная BIGQUERY_READONLY=true включает режим только чтения, BIGQUERY_WRITE_MODE принимает значения allowed, blocked и protected, где последний разрешает временные таблицы сессии, но не даёт менять постоянные наборы данных. BIGQUERY_MAXIMUM_BYTES_BILLED задаёт потолок объёма сканирования на один запрос: запрос, который его превысит, завершится ошибкой до выполнения, и вы за него не заплатите. По умолчанию число возвращаемых строк ограничено 50. Документация отдельно напоминает: подсказки клиента и подтверждения не заменяют права в самой базе, используйте для агента отдельную учётную запись с минимально нужными ролями.

Конфигурация MCP-клиента

Добавьте в файл конфигурации клиента (обычно mcp.json или claude_desktop_config.json) сервер с флагом --prebuilt=bigquery. Идентификатор проекта передаётся в переменной BIGQUERY_PROJECT:

{
  "mcpServers": {
    "toolbox-bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=bigquery",
        "--stdio"
      ],
      "env": {
        "BIGQUERY_PROJECT": "my-project-id"
      }
    }
  }
}

Остальные переменные необязательны: BIGQUERY_LOCATION, BIGQUERY_READONLY, BIGQUERY_WRITE_MODE, BIGQUERY_USE_CLIENT_OAUTH, BIGQUERY_SCOPES, BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT, BIGQUERY_MAXIMUM_BYTES_BILLED, BIGQUERY_ENDPOINT.

Свои инструменты через tools.yaml

Чтобы вместо готового набора описать собственные инструменты, запустите сервер с файлом конфигурации:

npx @toolbox-sdk/server --config tools.yaml

Источник BigQuery в таком файле описывается так (Application Default Credentials):

kind: source
name: my-bigquery-source
type: "bigquery"
project: "my-project-id"
# location: "US" # Optional: Specifies the location for query jobs.
# readOnly: false # Optional: Enforces read-only mode across all tools (defaults writeMode to "blocked").
# writeMode: "allowed" # One of: allowed, blocked, protected. Defaults to "allowed".
# allowedDatasets: # Optional: Restricts tool access to a specific list of datasets.
# - "my_dataset_1"
# - "other_project.my_dataset_2"
# maxQueryResultRows: 50 # Optional: Limits the number of rows returned by queries. Defaults to 50.
# maximumBytesBilled: 10737418240 # Optional: Per-query bytes scanned cap (in bytes).

Gemini CLI

Для Gemini CLI подготовлены расширения с готовыми инструментами. Установка Gemini CLI и расширения общего сервера Toolbox:

# Install Gemini CLI
npm install -g @google/gemini-cli
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox
# Run Gemini CLI
gemini