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, разрешение и прочие параметры.
• fetch_generation — докачка уже запущенной генерации по gen_... id. Нужен, когда MCP-клиент отвалился по таймауту, а генерация на стороне Polza успешно завершилась. Позволяет не перегенерировать (и не оплачивать повторно).
• upload_file — загрузка файлов в Polza Storage.
• show_output_stats — статистика локальной выходной директории.
• maintenance — обслуживание кэша, квот и БД.

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

• Claude Code или любой другой MCP-клиент
• uv
• Python 3.11+
• POLZA_AI_API_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")

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

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

git clone https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server.gitcd nanobanana-2-polzaia-mcp-serveruv synccp .env.example .env

Минимум в .env:

POLZA_AI_API_KEY=your_polza_api_keyPOLZA_BASE_URL=https://polza.ai/apiIMAGE_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"      }    }  }}

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

{  "mcpServers": {    "nanobanana-polza-local": {      "command": "uv",      "args": ["run", "python", "-m", "nanobanana_2_polzaia_mcp_server.server"],      "cwd": "/absolute/path/to/nanobanana-2-polzaia-mcp-server",      "env": {        "POLZA_AI_API_KEY": "your-polza-api-key-here",        "POLZA_BASE_URL": "https://polza.ai/api",        "IMAGE_OUTPUT_DIR": "/absolute/path/to/output"      }    }  }}

Claude Desktop

На macOS добавьте сервер в файл:

~/Library/Application Support/Claude/claude_desktop_config.json

Пример:

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

Переменные окружения

Публикация новой версии

# 1. bump версии в pyproject.toml и nanobanana_2_polzaia_mcp_server/__init__.py# 2. обновить CHANGELOG.md# 3. прогнать быстрый smoke-testPYTHONPYCACHEPREFIX=/tmp/pycache python3 -m compileall nanobanana_2_polzaia_mcp_serveruv build
# 4. публикация на PyPIuv publish --token "$UV_PUBLISH_TOKEN"
# 5. публикация метаданных в MCP Registrybrew install mcp-publisher   # один разmcp-publisher loginmcp-publisher publish

MCP Registry хранит только метаданные, сам пакет должен лежать на PyPI.

Используемые эндпоинты Polza

• POST /v1/media — запуск генерации
• GET /v1/media/{id} — статус и результат (используется для fetch_generation и поллинга)
• POST /v1/storage/upload — загрузка референса
• GET /v1/storage/files/{id} — метаданные файла
• DELETE /v1/storage/files/{id} — удаление файла

Лицензия

MIT. См. файл LICENSE.