Генерація зображень у 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. Проте у версії 0.55.1 CLI сформував такий конфіг:

{
  "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.

Стіна з невеликих зачинених дверей, одні з яких прочинені й світяться зсередини, редакційна ілюстрація

Доступні інструменти та їхня вартість

У сесії стають доступними дев'ять інструментів — той самий набір, що й у довіднику інструментів. Чотири з них є безкоштовними для виклику: list_models, get_account, get_result, list_generations. Решта тарифікуються за кожну генерацію з балансу вашого акаунта.

Що	Модель	Ціна
Зображення, 1K	Nano Banana 2 Lite	$0.03
Зображення, 512 → 4K	Nano Banana 2	$0.03 – $0.13
Зображення, 1K → 4K	Nano Banana Pro	$0.11 – $0.20
Відео, 3–10 с зі звуком	Gemini Omni Flash	$0.10 за секунду
Відео, 4–8 с	Сімейство Veo 3.1	до $4.40 за кліп
Мовлення	Gemini Flash TTS	$0.01 за 200 символів

Виклики для відео та пакетів зображень завжди попередньо надають розрахунок вартості. Агент отримує точну ціну, кошти наперед не списуються, а генерація розпочинається лише після підтвердження цієї суми. Відхилення фільтрами безпеки та збої upstream повертаються на баланс автоматично — для фонової пакетної обробки це критично важливо.

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

Монети поруч зі стопкою маленьких картин у рамках та кінострічкою у вигляді сходинок, редакційна ілюстрація

Генерація через сторонній сервер: у чому перевага?

Дві стежки до однієї сяючої брами: одна коротка й пряма, інша звивиста через контрольні пункти, редакційна ілюстрація

Звернення з Gemini CLI до графічної моделі Gemini через сторонній сервер на перший погляд здається обхідним шляхом. Існує прямий маршрут: створити платіжний акаунт Google Cloud, активувати 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 замість API-ключа?

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

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

Часті запитання

Де зберігається файл налаштувань?

У ~/.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 у конфігурації. Виключення має вищий пріоритет над включенням.

Чи працює це у спільному командному проєкті?

Визначте сервер на рівні проєкту, а ключ передавайте через змінну оточення, не записуючи його прямо у файл. Кожен розробник запускає export BB_KEY=… зі своїм ключем, і git-історія залишається чистою.

Що відбувається в разі збою генерації?

Кошти повертаються на баланс автоматично, включно з відхиленнями фільтрами безпеки. Якщо промпт знаходиться на межі дозволеного, має сенс спробувати ще раз: перевірка безпеки аналізує готові пікселі, а повторна спроба малює нове зображення.

Віддаєте перевагу візуальному інтерфейсу? Вебгенератор підтримує ті самі моделі з того самого балансу. У терміналі після підключення почніть із виклику list_models: він безкоштовний, показує актуальні ціни та підтверджує готовність з'єднання перед тим, як ви витратите три центи.