nanobanana-2-polzaia-mcp-server

Nano Banana 2 Polza MCP 服务

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

通过 Polza 和 Google Nano Banana 系列模型生成和编辑图像的 MCP 服务：

• 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（macOS 上运行 brew install uv）。
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）通常会为单次工具调用设置自己的超时，约为 60 秒。Nano Banana 2 并非总能在此时间内完成生成，因此客户端可能会在 Polza 返回结果之前显示 The read operation timed out。此时，Polza 服务仍会继续完成生成，并使用 gen_... ID 保存结果。

如果发生这种情况：

1. 在 Polza 网页界面（生成记录部分）查看 gen_... ID。
2. 使用该 ID 调用 fetch_generation — 服务会轮询状态并在本地保存文件。

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

从源代码运行：

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

环境变量

变量	必填	描述
POLZA_AI_API_KEY	是	Polza API 访问令牌
POLZA_BASE_URL	否	API 基础 URL，默认为 https://polza.ai/api
IMAGE_OUTPUT_DIR	否	已保存文件的目录，默认为 ~/nanobanana-images
POLZA_POLL_INTERVAL_SECONDS	否	状态轮询间隔，默认为 2
POLZA_POLL_TIMEOUT_SECONDS	否	等待生成的超时时间，默认为 120
POLZA_EXTERNAL_USER_ID	否	作为 user 传递给 Polza，用于反欺诈
RETURN_FULL_IMAGE	否	在 MCP 响应中返回完整图像，而非缩略图
NANOBANANA_MODEL	否	默认档位：auto、nb2、pro、flash

发布新版本

# 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 文件。