{
  "markdown": "# Nano Banana 2 Polza MCP Server\n\n`mcp-name: io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server`\n\nMCP-сервер для генерации и редактирования изображений через `Polza` с моделями семейства Google Nano Banana:\n\n- `google/gemini-3.1-flash-image-preview` — Nano Banana 2, модель по умолчанию\n- `google/gemini-3-pro-image-preview` — для сложных композиций и максимального качества\n- `google/gemini-2.5-flash-image` — для быстрых черновиков\n\nСервер отдаёт изображения настоящими MCP image content-блоками и параллельно — структурированный JSON с метаданными и подсказками по воспроизводимости.\n\n## Инструменты MCP\n\n- `generate_image` — генерация и редактирование. Поддерживает до трёх референсов для conditioning, выбор модели, aspect ratio, разрешение и прочие параметры.\n- `fetch_generation` — докачка уже запущенной генерации по `gen_...` id. Нужен, когда MCP-клиент отвалился по таймауту, а генерация на стороне Polza успешно завершилась. Позволяет не перегенерировать (и не оплачивать повторно).\n- `upload_file` — загрузка файлов в Polza Storage.\n- `show_output_stats` — статистика локальной выходной директории.\n- `maintenance` — обслуживание кэша, квот и БД.\n\n## Что нужно пользователю\n\n- `Claude Code` или любой другой MCP-клиент\n- `uv`\n- `Python 3.11+`\n- `POLZA_AI_API_KEY` (токен аккаунта Polza)\n\n## Быстрая установка за 2 минуты\n\nДля `Claude Code` / `VS Code`:\n\n1. Установите `uv` (`brew install uv` на macOS).\n2. В корне проекта создайте файл `.mcp.json`.\n3. Вставьте конфиг и подставьте свой Polza-ключ.\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-polza\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-2-polzaia-mcp-server@latest\"],\n      \"env\": {\n        \"POLZA_AI_API_KEY\": \"your-polza-api-key-here\",\n        \"POLZA_BASE_URL\": \"https://polza.ai/api\",\n        \"IMAGE_OUTPUT_DIR\": \"/Users/yourname/Documents/nanobanana\"\n      }\n    }\n  }\n}\n```\n\nПерезапустите Claude Code / VS Code.\n\n## Восстановление после таймаута\n\nMCP-клиенты (в том числе Claude Code) обычно имеют собственный таймаут на один tool call порядка 60 секунд. Nano Banana 2 укладывается в это окно не всегда, и клиент может вернуть `The read operation timed out` ещё до того, как Polza успела отдать результат. Сервер Polza в этот момент доводит генерацию до конца и сохраняет её под `gen_...` id.\n\nЕсли такое случилось:\n\n1. Посмотрите `gen_...` id в веб-интерфейсе Polza (раздел генераций).\n2. Вызовите `fetch_generation` с этим id — сервер опросит статус и сохранит файл локально.\n\n```\nfetch_generation(media_id=\"gen_2158267363095220225\",\n                 output_path=\"/abs/path/to/slide_3.png\")\n```\n\nПараметр `output_path` принимает как конкретный файл, так и директорию. При отсутствии параметра файл сохраняется в `IMAGE_OUTPUT_DIR`.\n\n## Локальная разработка\n\n```bash\ngit clone https://github.com/ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server.git\ncd nanobanana-2-polzaia-mcp-server\nuv sync\ncp .env.example .env\n```\n\nМинимум в `.env`:\n\n```env\nPOLZA_AI_API_KEY=your_polza_api_key\nPOLZA_BASE_URL=https://polza.ai/api\nIMAGE_OUTPUT_DIR=/absolute/path/to/output\n```\n\nЗапуск:\n\n```bash\nuv run python -m nanobanana_2_polzaia_mcp_server.server\n```\n\n## Claude Code / VS Code (варианты конфига)\n\nУстановленный через PyPI пакет — рекомендуемый вариант:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-polza\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-2-polzaia-mcp-server@latest\"],\n      \"env\": {\n        \"POLZA_AI_API_KEY\": \"your-polza-api-key-here\",\n        \"POLZA_BASE_URL\": \"https://polza.ai/api\",\n        \"IMAGE_OUTPUT_DIR\": \"/Users/demo/Documents/nanobanana\"\n      }\n    }\n  }\n}\n```\n\nЗапуск из исходников:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-polza-local\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"python\", \"-m\", \"nanobanana_2_polzaia_mcp_server.server\"],\n      \"cwd\": \"/absolute/path/to/nanobanana-2-polzaia-mcp-server\",\n      \"env\": {\n        \"POLZA_AI_API_KEY\": \"your-polza-api-key-here\",\n        \"POLZA_BASE_URL\": \"https://polza.ai/api\",\n        \"IMAGE_OUTPUT_DIR\": \"/absolute/path/to/output\"\n      }\n    }\n  }\n}\n```\n\n## Claude Desktop\n\nНа macOS добавьте сервер в файл:\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\nПример:\n\n```json\n{\n  \"mcpServers\": {\n    \"nanobanana-polza\": {\n      \"command\": \"uvx\",\n      \"args\": [\"nanobanana-2-polzaia-mcp-server@latest\"],\n      \"env\": {\n        \"POLZA_AI_API_KEY\": \"your-polza-api-key-here\",\n        \"POLZA_BASE_URL\": \"https://polza.ai/api\",\n        \"IMAGE_OUTPUT_DIR\": \"/Users/demo/Documents/nanobanana\"\n      }\n    }\n  }\n}\n```\n\n## Переменные окружения\n\n| Переменная | Обязательно | Описание |\n|---|---|---|\n| `POLZA_AI_API_KEY` | да | Токен доступа к Polza API |\n| `POLZA_BASE_URL` | нет | База API, по умолчанию `https://polza.ai/api` |\n| `IMAGE_OUTPUT_DIR` | нет | Директория для сохранённых файлов, по умолчанию `~/nanobanana-images` |\n| `POLZA_POLL_INTERVAL_SECONDS` | нет | Интервал поллинга статуса, по умолчанию `2` |\n| `POLZA_POLL_TIMEOUT_SECONDS` | нет | Таймаут ожидания генерации, по умолчанию `120` |\n| `POLZA_EXTERNAL_USER_ID` | нет | Передаётся в Polza как `user` для антифрода |\n| `RETURN_FULL_IMAGE` | нет | Возвращать полное изображение в MCP-ответе вместо thumbnail |\n| `NANOBANANA_MODEL` | нет | Дефолтный tier: `auto`, `nb2`, `pro`, `flash` |\n\n## Публикация новой версии\n\n```bash\n# 1. bump версии в pyproject.toml и nanobanana_2_polzaia_mcp_server/__init__.py\n# 2. обновить CHANGELOG.md\n# 3. прогнать быстрый smoke-test\nPYTHONPYCACHEPREFIX=/tmp/pycache python3 -m compileall nanobanana_2_polzaia_mcp_server\nuv build\n\n# 4. публикация на PyPI\nuv publish --token \"$UV_PUBLISH_TOKEN\"\n\n# 5. публикация метаданных в MCP Registry\nbrew install mcp-publisher   # один раз\nmcp-publisher login\nmcp-publisher publish\n```\n\nMCP Registry хранит только метаданные, сам пакет должен лежать на PyPI.\n\n## Используемые эндпоинты Polza\n\n- `POST /v1/media` — запуск генерации\n- `GET /v1/media/{id}` — статус и результат (используется для `fetch_generation` и поллинга)\n- `POST /v1/storage/upload` — загрузка референса\n- `GET /v1/storage/files/{id}` — метаданные файла\n- `DELETE /v1/storage/files/{id}` — удаление файла\n\n## Лицензия\n\nMIT. См. файл `LICENSE`.\n",
  "bytes": 6142,
  "sha": "a1d8c8023a02856a006473ea05606173706d366343f6e129b5dd00e1f9ef0a77",
  "repo_slug": "ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ivanantigravity_lgtm_nanobanan_4ba4a8b2/readme"
}