Nanobanana 2 Polzaia MCP server

Nano Banana 2 Polza MCP Server

mcp-name: io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server

MCP-сервер для генерации и редактирования изображений через Polza с моделями семейства Google Nano Banana:

• google/gemini-3.1-flash-image-preview — Nano Banana 2, модель по умолчанию
• google/gemini-3-pro-image-preview — для сложных композиций и максимального качества
• google/gemini-2.5-flash-image — для быстрых черновиков

Сервер отдаёт изображения настоящими MCP image content-блоками и параллельно — структурированный JSON с метаданными и подсказками по воспроизводимости.

Инструменты MCP

• generate_image — генерация и редактирование. Поддерживает до трёх референсов для conditioning, выбор модели, aspect ratio, разрешение и прочие параметры.
• fetchgeneration — докачка уже запущенной генерации по gen... id. Нужен, когда MCP-клиент отвалился по таймауту, а генерация на стороне Polza успешно завершилась. Позволяет не перегенерировать (и не оплачивать повторно).
• upload_file — загрузка файлов в Polza Storage.
• showoutputstats — статистика локальной выходной директории.
• maintenance — обслуживание кэша, квот и БД.

Что нужно пользователю

• Claude Code или любой другой MCP-клиент
• uv
• Python 3.11+
• POLZAAIAPI_KEY (токен аккаунта Polza)

Быстрая установка за 2 минуты

Для Claude Code / VS Code:

1. Установите uv (brew install uv на macOS).
2. В корне проекта создайте файл .mcp.json.
3. Вставьте конфиг и подставьте свой Polza-ключ.

{
  "mcpServers": {
    "nanobanana-polza": {
      "command": "uvx",
      "args": ["nanobanana-2-polzaia-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/Users/yourname/Documents/nanobanana"
      }
    }
  }
}

Перезапустите Claude Code / VS Code.

Восстановление после таймаута

MCP-клиенты (в том числе Claude Code) обычно имеют собственный таймаут на один tool call порядка 60 секунд. Nano Banana 2 укладывается в это окно не всегда, и клиент может вернуть The read operation timed out ещё до того, как Polza успела отдать результат. Сервер Polza в этот момент доводит генерацию до конца и сохраняет её под gen_... id.

Если такое случилось:

1. Посмотрите gen_... id в веб-интерфейсе Polza (раздел генераций).
2. Вызовите fetch_generation с этим id — сервер опросит статус и сохранит файл локально.

fetch_generation(media_id="gen_2158267363095220225",
                 output_path="/abs/path/to/slide_3.png")

Параметр outputpath принимает как конкретный файл, так и директорию. При отсутствии параметра файл сохраняется в IMAGEOUTPUT_DIR.

Локальная разработка

git clone https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server.git
cd nanobanana-2-polzaia-mcp-server
uv sync
cp .env.example .env

Минимум в .env:

POLZA_AI_API_KEY=your_polza_api_key
POLZA_BASE_URL=https://polza.ai/api
IMAGE_OUTPUT_DIR=/absolute/path/to/output

Запуск:

uv run python -m nanobanana_2_polzaia_mcp_server.server

Claude Code / VS Code (варианты конфига)

Установленный через PyPI пакет — рекомендуемый вариант:

{
  "mcpServers": {
    "nanobanana-polza": {
      "command": "uvx",
      "args": ["nanobanana-2-polzaia-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/Users/demo/Documents/nanobanana"
      }
    }
  }
}

Запуск из исходников:

Shortened. The full README is on GitHub.