Генерация изображений в Gemini CLI: настройка MCP-сервера

Gemini CLI — это открытый терминальный агент от Google, а MCP — протокол, через который он обращается к внешним инструментам. Подключите его к удаленному MCP-серверу, и та же сессия чата, которая правит код, сможет создавать изображения, видео и речь, сохраняя файлы прямо в вашу рабочую директорию.

Короткий ответ: выполните gemini mcp add --transport http --scope user bananabanana https://bananabanana.pro/api/mcp -H "Authorization: Bearer $BB_KEY", подтвердите доверие к папке при запросе CLI, затем проверьте статус командой gemini mcp list — должна появиться зеленая надпись Connected. Изображения стоят от $0.03 за генерацию со списанием с вашего баланса.

Все описанное ниже тестировалось в Gemini CLI 0.55.1 на 17 августа 2026 года с действующим ключом bb_live_…. Там, где официальная документация расходится с реальным поведением CLI, об этом сказано прямо.

Настройка без лишних слов

Всего две команды. Первая регистрирует сервер:

export BB_KEY=bb_live_…   # create one at https://bananabanana.pro/profile
 
gemini mcp add --transport http --scope user \
  bananabanana https://bananabanana.pro/api/mcp \
  -H "Authorization: Bearer $BB_KEY"

Вторая проверяет подключение:

gemini mcp list
# ✓ bananabanana: https://bananabanana.pro/api/mcp (http) - Connected

Если вместо Connected вы видите Disabled, прочтите следующий раздел, прежде чем что-то менять. На этой мелочи я сам потерял минут пять.

Пять нюансов, о которых молчит документация

Доверие к директории молча отключает всё. Запустите gemini mcp list в папке, которой CLI не доверяет, и увидите:

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

○ bananabanana: https://bananabanana.pro/api/mcp (http) - Disabled

Обратите внимание на вторую строку: даже сервер с --scope user остается отключенным. При первом интерактивном запуске CLI спрашивает подтверждение; при автоматизации статус доверия хранится в ~/.gemini/trustedFolders.json как обычный список путей со значением TRUST_FOLDER. Логика здравая, но поведение при ошибке неудачное — статус "Disabled" никак не намекает на проверку папки.

Команда gemini mcp add записывает url, а не httpUrl. Документация описывает параметр httpUrl для Streamable HTTP. В реальности CLI 0.55.1 сформировал следующий конфиг:

{
  "mcpServers": {
    "bananabanana": {
      "url": "https://bananabanana.pro/api/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $BB_KEY" }
    }
  }
}

Оба формата работают. Но если вы сравниваете рабочий конфиг от CLI с примером из документации, покажется, что в одном из них ошибка. На самом деле работают оба.

Область видимости по умолчанию — project, и ключ попадает в репозиторий. Если не указать --scope user, ключ запишется в .gemini/settings.json внутри проекта. После первого git add . он окажется в истории коммитов. Всегда используйте --scope user или передавайте заголовок через переменную окружения, как показано в примере.

Подстановка $BB_KEY работает, но сбоит молча. Когда переменная экспортирована — статус Connected. Откройте новый терминал без экспорта переменной, и тот же конфиг покажет Disconnected вместо понятной ошибки авторизации. Стоит добавить строчку экспорта в свой профиль командной оболочки.

Gemini CLI опрашивает SSE и получает 405. В логах сервера при подключении видна последовательность: POST initialize (200), POST notification (202), GET /api/mcp (405), POST tools/list (200). GET-запрос — это попытка CLI открыть Server-Sent Events на stateless-сервере. Она завершается с 405, CLI спокойно продолжает работу, и все функционирует штатно. Если поднимаете свой MCP-сервер, не тратьте время на этот 405.

Доступные инструменты и стоимость

В сессии появляется девять инструментов — тот же набор, что и в описании API. Четыре из них бесплатны для вызова: list_models, get_account, get_result, list_generations. Остальные тарифицируются за каждую генерацию с баланса аккаунта.

Генерации видео и пакетов изображений всегда предварительно запрашивают подтверждение стоимости: агент получает точную цену, баланс пока не трогается, а генерация запускается только после подтверждения этой суммы. Ошибки фильтра безопасности и сбои upstream автоматически возвращаются на баланс — при пакетной генерации в фоне это крайне важно.

При пополнении баланса начисляются бонусы: 5% от $50, 10% от $100, а активный промокод добавляет еще 10% к сумме депозита. Пополнение на $100 с промокодом зачислит $120.

Генерация через сторонний сервер: в чем смысл?

На первый взгляд запрос из Gemini CLI к графической модели Gemini через сторонний сервер выглядит обходным путем. Есть прямой маршрут: привязать платежный аккаунт Google Cloud, настроить доступ к Model API, выписать учетные данные, следить за региональными квотами. Отличный вариант, если ваша задача — построить инфраструктуру.

Наш подход решает другую проблему. Один токен, предоплаченный баланс, никаких платежных профилей облака, тикетов на расширение квот и привязки к регионам. Заодно через то же подключение доступны видеомодели Veo и Omni, а также TTS с оплатой за генерацию, а не за проект. Если цель — просто создавать контент, а не обслуживать облачный стек, это куда практичнее.

На больших объемах инфраструктурный путь в облаке выйдет дешевле. Но наш вариант позволяет начать за пару минут и гарантирует, что вы случайно не оставите работающий счетчик на балансе облака.

Если вы работаете в других редакторах, этот же сервер подключается к Claude Code, Cursor и Codex с тем же API-ключом и соответствующим конфигом.

Практический кейс: иллюстрации для документации

Вот реальная задача, для которой этот сетап подходит идеально: репозиторий с папкой docs/, двенадцать страниц, для каждой нужна обложка в едином визуальном стиле.

Промпт в сессии:

Read every heading in docs/*.md. For each file, generate a 16:9 illustration matching the page topic, in this style: editorial illustration, pastel paper background, dark ink details, violet and amber accents, no text. Use nano-banana-pro. Save each as docs/img/.png and add the image reference under the page title.

Агент считывает файлы, вызывает generate_image для каждой страницы, ожидает через get_result, скачивает файлы и прописывает markdown-разметку. Двенадцать изображений по $0.11 обходятся в $1.32, и всё это выполняется в фоне, пока вы пьете кофе. Все иллюстрации в этой статье сгенерированы по той же схеме на Nano Banana Pro с единым описанием стиля.

Пара советов перед запуском: сначала сгенерируйте одну тестовую картинку для проверки стиля (ошибка в промпте на 12 файлов потратит $1.32 впустую), и не используйте флаг --trust без надобности — запрос подтверждения на каждый платный вызов инструмента защитит от случайных циклов агента.

Работает ли OAuth вместо ключа?

В документации Gemini CLI заявлена поддержка OAuth 2.0 для удаленных MCP-серверов с механизмом discovery и командой /mcp auth. Наш сервер представляет собой полноценный OAuth 2.1 authorization server (динамическая регистрация клиентов, PKCE S256, RFC 9728 discovery), и клиенты вроде Claude Code и claude.ai авторизуются именно так без ручного ввода ключа.

Сценарий с API-ключом проверен от начала до конца и работает стабильно. Авторизацию по OAuth в Gemini CLI в этой сессии мы отдельно не валидировали, поэтому рассматривайте ее как потенциально рабочую, но не гарантированную. Создание API-ключа занимает десять секунд, и он действует бессрочно до ручного отзыва.

Частые вопросы

Где находится файл настроек?

~/.gemini/settings.json для уровня пользователя (user scope), .gemini/settings.json для уровня проекта (project scope). Команда gemini mcp add --scope user сохраняет данные в первый файл.

Почему статус сервера показывает Disabled?

Директория не добавлена в список доверенных. Подтвердите доверие в терминале при запуске или добавьте путь в ~/.gemini/trustedFolders.json со значением TRUST_FOLDER. Серверы уровня пользователя в недоверенных папках тоже блокируются.

Можно ли ограничить список инструментов для модели?

Да. Используйте параметры --include-tools и --exclude-tools в команде gemini mcp add или поля includeTools / excludeTools в настройках. Исключение имеет приоритет над включением — удобно, если нужны картинки, но хочется закрыть доступ к видео.

Как настроить сервер в общем командном репозитории?

Укажите сервер в области видимости проекта (project scope), а ключ передавайте через переменную окружения, не прописывая его в файл. Каждый разработчик выполняет export BB_KEY=… со своим ключом, а конфиг в git остается чистым.

Что происходит при ошибке генерации?

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

Предпочитаете интерфейс вместо терминала? В веб-генераторе доступны те же модели с общего баланса. В CLI после подключения начните с команды list_models — она бесплатна, покажет актуальные цены и подтвердит работоспособность цепочки.