nanobanana-2-polzaia-mcp-server

Nano Banana 2 Polza MCP サーバー

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

Google Nano Banana ファミリーのモデルを使用して、Polza 経由で画像を生成・編集する MCP サーバーです。

• google/gemini-3.1-flash-image-preview — Nano Banana 2、デフォルトモデル
• google/gemini-3-pro-image-preview — 複雑な構図や最高品質向け
• google/gemini-2.5-flash-image — 高速な下書き向け

このサーバーは、画像を実際の MCP 画像コンテンツブロックとして返すとともに、再現性に関するメタデータやヒントを含む構造化 JSON も返します。

MCP ツール

• generate_image — 画像の生成と編集。コンディショニング用の参照画像を最大3枚指定でき、モデル、アスペクト比、解像度、その他のパラメーターを選択できます。
• fetch_generation — gen_... ID を指定して、すでに開始した生成の結果を取得します。MCP クライアントがタイムアウトで切断されたものの、Polza 側で生成が正常に完了した場合に必要です。再生成（および重複した支払い）を避けられます。
• upload_file — Polza Storage にファイルをアップロードします。
• show_output_stats — ローカルの出力ディレクトリの統計情報を表示します。
• maintenance — キャッシュ、クォータ、DB のメンテナンスを行います。

必要なもの

• 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 を含む）には通常、1回のツール呼び出しに対する独自のタイムアウトがあり、その時間は約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 ファイルを参照してください。