io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server
Nano Banana MCP server backed by Polza media and storage APIs.
Open source Open in the app JSON README (API)
About
Nano Banana MCP server backed by Polza media and storage APIs.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ivanantigravity-lgtm
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.0
- Stars
- 1
- Forks
- 1
- Last push
- 2026-04-22T17:19:56Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:12
- Updated
- 2026-08-29 04:00:12
- Origin id
io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server
README
# 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-ключ.
```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/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`.
## Локальная разработка
```bash
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`:
```env
POLZA_AI_API_KEY=your_polza_api_key
POLZA_BASE_URL=https://polza.ai/api
IMAGE_OUTPUT_DIR=/absolute/path/to/output
```
Запуск:
```bash
uv run python -m nanobanana_2_polzaia_mcp_server.server
```
## Claude Code / VS Code (варианты конфига)
Установленный через PyPI пакет — рекомендуемый вариант:
```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"
}
}
}
}
```
Запуск из исходников:
```json
{
"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`
Пример:
```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"
}
}
}
}
```
## Переменные окружения
| Переменная | Обязательно | Описание |
|---|---|---|
| `POLZA_AI_API_KEY` | да | Токен доступа к Polza API |
| `POLZA_BASE_URL` | нет | База API, по умолчанию `https://polza.ai/api` |
| `IMAGE_OUTPUT_DIR` | нет | Директория для сохранённых файлов, по умолчанию `~/nanobanana-images` |
| `POLZA_POLL_INTERVAL_SECONDS` | нет | Интервал поллинга статуса, по умолчанию `2` |
| `POLZA_POLL_TIMEOUT_SECONDS` | нет | Таймаут ожидания генерации, по умолчанию `120` |
| `POLZA_EXTERNAL_USER_ID` | нет | Передаётся в Polza как `user` для антифрода |
| `RETURN_FULL_IMAGE` | нет | Возвращать полное изображение в MCP-ответе вместо thumbnail |
| `NANOBANANA_MODEL` | нет | Дефолтный tier: `auto`, `nb2`, `pro`, `flash` |
## Публикация новой версии
```bash
# 1. bump версии в pyproject.toml и nanobanana_2_polzaia_mcp_server/__init__.py
# 2. обновить CHANGELOG.md
# 3. прогнать быстрый smoke-test
PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m compileall nanobanana_2_polzaia_mcp_server
uv build
# 4. публикация на PyPI
uv publish --token "$UV_PUBLISH_TOKEN"
# 5. публикация метаданных в MCP Registry
brew install mcp-publisher # один раз
mcp-publisher login
mcp-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`.