Content
# Nano Banana 2 Polza MCP Server
`mcp-name: io.github.ivanantigravity-lgtm/nanobanana-2-polzaia-mcp-server`
MCP server for generating and editing images via `Polza` with Google Nano Banana models:
- `google/gemini-3.1-flash-image-preview` — Nano Banana 2, default model
- `google/gemini-3-pro-image-preview` — for complex compositions and maximum quality
- `google/gemini-2.5-flash-image` — for quick drafts
The server returns images as real MCP image content blocks and, in parallel, structured JSON with metadata and reproducibility hints.
## MCP Tools
- `generate_image` — generation and editing. Supports up to three references for conditioning, model selection, aspect ratio, resolution, and other parameters.
- `fetch_generation` — downloading an already launched generation by `gen_...` id. Needed when the MCP client has timed out, but the generation on the Polza side has successfully completed. Allows you not to re-generate (and not to pay again).
- `upload_file` — uploading files to Polza Storage.
- `show_output_stats` — statistics of the local output directory.
- `maintenance` — maintenance of cache, quotas, and database.
## Requirements for Users
- `Claude Code` or any other MCP client
- `uv`
- `Python 3.11+`
- `POLZA_AI_API_KEY` (Polza account token)
## Quick Installation in 2 Minutes
For `Claude Code` / `VS Code`:
1. Install `uv` (`brew install uv` on macOS).
2. Create a `.mcp.json` file in the project root.
3. Insert the config and substitute your Polza key.
```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"
}
}
}
}
```
Restart Claude Code / VS Code.
## Recovery After Timeout
MCP clients (including Claude Code) usually have their own timeout for one tool call of about 60 seconds. Nano Banana 2 does not always fit within this window, and the client may return `The read operation timed out` even before Polza has managed to deliver the result. The Polza server at this moment brings the generation to the end and saves it under the `gen_...` id.
If this happens:
1. Look at the `gen_...` id in the Polza web interface (generation section).
2. Call `fetch_generation` with this id — the server will query the status and save the file locally.
```python
fetch_generation(media_id="gen_2158267363095220225",
output_path="/abs/path/to/slide_3.png")
```
The `output_path` parameter accepts both a specific file and a directory. If the parameter is absent, the file is saved in `IMAGE_OUTPUT_DIR`.
## Local Development
```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
```
Minimum in `.env`:
```env
POLZA_AI_API_KEY=your_polza_api_key
POLZA_BASE_URL=https://polza.ai/api
IMAGE_OUTPUT_DIR=/absolute/path/to/output
```
Launch:
```bash
uv run python -m nanobanana_2_polzaia_mcp_server.server
```
## Claude Code / VS Code (Config Options)
The package installed via PyPI is the recommended option:
```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"
}
}
}
}
```
Launch from sources:
```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
On macOS, add the server to the file:
`~/Library/Application Support/Claude/claude_desktop_config.json`
Example:
```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"
}
}
}
}
```
## Environment Variables
| Variable | Required | Description |
|---|---|---|
| `POLZA_AI_API_KEY` | yes | Polza API access token |
| `POLZA_BASE_URL` | no | API base, default `https://polza.ai/api` |
| `IMAGE_OUTPUT_DIR` | no | Directory for saved files, default `~/nanobanana-images` |
| `POLZA_POLL_INTERVAL_SECONDS` | no | Polling status interval, default `2` |
| `POLZA_POLL_TIMEOUT_SECONDS` | no | Generation timeout, default `120` |
| `POLZA_EXTERNAL_USER_ID` | no | Passed to Polza as `user` for anti-fraud |
| `RETURN_FULL_IMAGE` | no | Return the full image in the MCP response instead of thumbnail |
| `NANOBANANA_MODEL` | no | Default tier: `auto`, `nb2`, `pro`, `flash` |
## Publishing a New Version
```bash
# 1. bump version in pyproject.toml and nanobanana_2_polzaia_mcp_server/__init__.py
# 2. update CHANGELOG.md
# 3. run a quick smoke-test
PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m compileall nanobanana_2_polzaia_mcp_server
uv build
# 4. publish to PyPI
uv publish --token "$UV_PUBLISH_TOKEN"
# 5. publish metadata to MCP Registry
brew install mcp-publisher # once
mcp-publisher login
mcp-publisher publish
```
MCP Registry stores only metadata, the package itself must be on PyPI.
## Used Polza Endpoints
- `POST /v1/media` — launch generation
- `GET /v1/media/{id}` — status and result (used for `fetch_generation` and polling)
- `POST /v1/storage/upload` — reference upload
- `GET /v1/storage/files/{id}` — file metadata
- `DELETE /v1/storage/files/{id}` — file deletion
## License
MIT. See `LICENSE` file.
