Nanobanana Mcp Server

Nano Banana MCP サーバー 🍌

Google の Gemini モデルを通じて、インテリジェントなモデル選択による AI 画像生成機能を提供する、本番環境対応の Model Context Protocol（MCP） サーバーです。

⭐ 新登場：Nano Banana 2 — Gemini 3.1 Flash Image！🍌🚀

Nano Banana 2（gemini-3.1-flash-image-preview）がデフォルトモデルになりました。Flash の速度で Pro レベルの品質を実現します。

• 🍌 Flash の速度＋4K 品質：Gemini 2.5 Flash と同等のレイテンシで、最大 3840px に対応
• 🌐 Google 検索によるグラウンディング：現実世界の知識を活用し、事実に即した画像を生成
• 🎯 被写体の一貫性：1 シーンあたり最大 5 人のキャラクターと 14 個のオブジェクトに対応
• ✍️ 高精度なテキスト描画：画像内にテキストを鮮明に配置
• 🏆 Gemini 3 Pro Image も引き続き利用可能。最大限の推論能力が必要な場合に適しています

✨ 機能

• 🎨 マルチモデル AI 画像生成：インテリジェントな自動選択に対応した 3 種類の Gemini モデル
• 🍌 Gemini 3.1 Flash Image（NB2）：デフォルトモデル。グラウンディング機能を備え、Flash の速度で 4K 解像度を実現
• 🏆 Gemini 3 Pro Image：最も複雑な構図に対応する、最大限の推論能力
• ⚡ Gemini 2.5 Flash Image：大量の迅速なプロトタイピングに適した従来の Flash モデル
• 🤖 スマートなモデル選択：プロンプトに基づいて NB2 または Pro に自動で振り分け
• 📐 アスペクト比の制御 ⭐ 新機能：出力サイズを指定可能（1:1、16:9、9:16、21:9 など）
• 📋 スマートテンプレート：写真撮影、デザイン、編集向けの組み込みプロンプトテンプレート
• 📁 ファイル管理：Gemini Files API を使用したファイルのアップロードと管理
• 🔍 リソースの検出：MCP リソースを通じてテンプレートやファイルのメタデータを参照
• 🛡️ 本番環境対応：包括的なエラー処理、ログ記録、検証
• ⚡ 高パフォーマンス：インテリジェントなキャッシュを備えた最適化アーキテクチャ

🚀 クイックスタート

前提条件

1. Google Gemini API キー — こちらから無料で取得
2. Python 3.11 以降（開発時のみ）

インストール

オプション 1：MCP Registry からインストール（推奨） このサーバーは Model Context Protocol Registry で利用できます。「nanobanana」で検索するか、以下の MCP 名を MCP クライアントで使用してください。

mcp-name: io.github.zhongweili/nanobanana-mcp-server

オプション 2：uvx を使用

uvx nanobanana-mcp-server@latest

オプション 3：pip を使用

pip install nanobanana-mcp-server

🔧 設定

認証方法

Nano Banana は、NANOBANANA_AUTH_METHOD を使って次の 2 つの認証方法をサポートしています。

1. API キー（api_key）：GEMINI_API_KEY を使用します。ローカル開発やシンプルなデプロイに最適です。
2. Vertex AI ADC（vertex_ai）：Google Cloud Application Default Credentials を使用します。Google Cloud（Cloud Run、GKE、GCE）上の本番環境に最適です。
3. 自動（auto）：API キーが設定されていれば API キーを使用し、設定されていなければ Vertex AI を試します。

1. API キー認証（デフォルト）

環境変数 GEMINI_API_KEY を設定します。

2. Vertex AI 認証（Google Cloud）

必須の環境変数：

• NANOBANANA_AUTH_METHOD=vertex_ai（または auto）
• GCP_PROJECT_ID=your-project-id
• GCP_REGION=global（デフォルト値。Gemini 3 Pro Image と NB2 で必須です。従来の 2.5 Flash Image モデルを使用する場合のみ、us-central1 を指定してください。）

前提条件：

• Vertex AI API を有効化します：gcloud services enable aiplatform.googleapis.com
• サービスアカウントに IAM ロール roles/aiplatform.user を付与します。

Claude Desktop

オプション 1：公開済みサーバーを使用（推奨）

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

オプション 2：ローカルソースを使用（開発用）

ソースコードから実行する場合は、ローカルのインストール先を指定します。

{
  "mcpServers": {
    "nanobanana-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "nanobanana_mcp_server.server"],
      "cwd": "/absolute/path/to/nanobanana-mcp-server",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

オプション 3：Vertex AI の使用（ADC）

API キーの代わりに Google Cloud Application Default Credentials で認証するには：

{
  "mcpServers": {
    "nanobanana-adc": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "NANOBANANA_AUTH_METHOD": "vertex_ai",
        "GCP_PROJECT_ID": "your-project-id",
        "GCP_REGION": "global"
      }
    }
  }
}

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Claude Code（VS Code 拡張機能）

VS Code でインストールして設定します：

1. Claude Code 拡張機能をインストールします
2. コマンドパレット（Cmd/Ctrl + Shift + P）を開きます
3. 「Claude Code: Add MCP Server」を実行します
4. 次のように設定します：

   {
     "name": "nanobanana",
     "command": "uvx",
     "args": ["nanobanana-mcp-server@latest"],
     "env": {
       "GEMINI_API_KEY": "your-gemini-api-key-here"
     }
   }
   

Cursor

Cursor の MCP 設定に追加します：

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

OpenAI Codex

~/.codex/config.toml（グローバル）または .codex/config.toml（プロジェクト単位）に追加します：

[mcp_servers.nanobanana]
command = "uvx"
args = ["nanobanana-mcp-server@latest"]

[mcp_servers.nanobanana.env]
GEMINI_API_KEY = "your-gemini-api-key-here"

または、CLI から追加します：

codex mcp add

Codex は、同じ config.toml を使用して CLI と VSCode 拡張機能の両方をサポートします。追加すると、Codex はコーディングセッション中に generate_image、edit_image、upload_file ツールを直接呼び出せます。

注：Codex の設定ファイルは、CLI と IDE 拡張機能で共有されています。TOML の構文エラーがあると両方が同時に動作しなくなるため、編集内容を注意深く検証してください。

Continue.dev（VS Code/JetBrains）

config.json に追加します：

{
  "mcpServers": [
    {
      "name": "nanobanana",
      "command": "uvx",
      "args": ["nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  ]
}

Open WebUI

Open WebUI の設定で構成します：

{
  "mcp_servers": {
    "nanobanana": {
      "command": ["uvx", "nanobanana-mcp-server@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Gemini CLI / 汎用 MCP クライアント

# Set environment variable
export GEMINI_API_KEY="your-gemini-api-key-here"

# Run server in stdio mode
uvx nanobanana-mcp-server@latest

# Or with pip installation
python -m nanobanana_mcp_server.server

🤖 モデルの選択

Nano Banana は、インテリジェントな自動選択に対応した 3 つの Gemini モデルをサポートしています。

🍌 NB2 — Nano Banana 2（Gemini 3.1 Flash Image）⭐ デフォルト

Flash の速度と Pro レベルの品質を両立 — 両方の長所を備えています

• 品質：本番環境で使用できる 4K 出力
• 解像度：最大 4K（3840px）
• 速度：画像 1 枚あたり約 2～4 秒（Flash クラスのレイテンシ）
• 主な機能：
  • 🌐 Google 検索によるグラウンディング：事実に即した画像を生成するための現実世界の知識
  • 🎯 被写体の一貫性：1 つのシーンにつき最大 5 人のキャラクターと 14 個のオブジェクト
  • ✍️ 高精度なテキスト描画：画像内に明瞭で適切に配置されたテキスト
• 最適な用途：ほぼあらゆる用途 — 本番用アセット、マーケティング、写真、テキストオーバーレイ
• model_tier："nb2"（または "auto" — NB2 が自動選択時のデフォルト）

🏆 Pro モデル — Nano Banana Pro（Gemini 3 Pro Image）

最も難しい構図に対応する、最大限の推論能力

• 品質：利用可能な最高品質
• 解像度：最大 4K（3840px）
• 速度：画像 1 枚あたり約 5～8 秒
• 主な機能：
  • 🧠 高度な推論：思考レベルを設定可能（LOW/HIGH）
  • 🌐 Google 検索によるグラウンディング：現実世界の知識を統合
  • 📐 メディア解像度の制御：ビジョン処理の詳細度を細かく調整
• 最適な用途：複雑な物語性のあるシーン、精緻な構図、最大限の推論が必要な場合
• model_tier："pro"

⚡ Flash モデル（Gemini 2.5 Flash Image）

大量生成や迅速な反復に適した旧モデル

• 速度：非常に高速（2～3 秒）
• 解像度：最大 1024px
• 最適な用途：大量生成、4K が不要な場合の素早い下書き
• model_tier："flash"

🤖 自動選択（推奨）

デフォルトでは、サーバーは AUTO モードを使用し、Pro のより深い推論が明らかに必要な場合を除いて NB2 に振り分けます。

Pro モデルが選択される場合：

• 品質に関する強いキーワード：「4K」、「professional」、「production」、「high-res」、「HD」
• 高い思考レベルが指定された場合：thinking_level="HIGH"
• 複数の入力画像を使ったマルチ画像コンディショニング

NB2 モデルが選択される場合（デフォルト）：

• 標準的なリクエスト、日常的な画像生成
• 速度に関するキーワード：「quick」、「draft」、「sketch」、「rapid」
• 大量のバッチ生成（n > 2）

使用例

# Automatic selection (recommended) — routes to NB2 by default
"A cat sitting on a windowsill"             # → NB2 (default)
"Quick sketch of a cat"                     # → NB2 (speed keyword, NB2 is fast enough)
"Professional 4K product photo"             # → Pro (strong quality keywords)

# Explicit NB2 selection
generate_image(
    prompt="Product photo on white background",
    model_tier="nb2",              # Nano Banana 2 (Flash speed + 4K)
    resolution="4k",
    enable_grounding=True
)

# Leverage Nano Banana Pro for complex reasoning
generate_image(
    prompt="Cinematic scene: three characters in a tense standoff at dusk",
    model_tier="pro",              # Pro for deep reasoning
    resolution="4k",
    thinking_level="HIGH",         # Enhanced reasoning
    enable_grounding=True
)

# Legacy Flash for high-volume drafts
generate_image(
    prompt="Simple icon",
    model_tier="flash"             # Fast 1024px generation
)

# Control aspect ratio for different formats ⭐ NEW!
generate_image(
    prompt="Cinematic landscape at sunset",
    aspect_ratio="21:9"            # Ultra-wide cinematic format
)

generate_image(
    prompt="Instagram post about coffee",
    aspect_ratio="1:1"             # Square format for social media
)

generate_image(
    prompt="YouTube thumbnail design",
    aspect_ratio="16:9"            # Standard video format
)

generate_image(
    prompt="Mobile wallpaper of mountain vista",
    aspect_ratio="9:16"            # Portrait format for phones
)

📐 アスペクト比の制御

aspect_ratio パラメーターで出力画像の寸法を制御します。

サポートされているアスペクト比：

• 1:1 - 正方形（Instagram、プロフィール写真）
• 4:3 - クラシックな写真形式
• 3:4 - 縦向き
• 16:9 - ワイドスクリーン（YouTube のサムネイル、プレゼンテーション）
• 9:16 - モバイル向け縦向き（スマートフォンの壁紙、ストーリー）
• 21:9 - ウルトラワイドシネマティック
• 2:3、3:2、4:5、5:4 - さまざまな写真形式

# Examples for different use cases
generate_image(
    prompt="Product showcase for e-commerce",
    aspect_ratio="3:4",    # Portrait format, good for product pages
    model_tier="pro"
)

generate_image(
    prompt="Social media banner for Facebook",
    aspect_ratio="16:9"    # Landscape banner format
)

注：アスペクト比は Flash モデルと Pro モデルの両方で使用できます。高解像度で特定のアスペクト比を指定する場合は、Pro モデルで resolution="4k" を使用すると最適な結果が得られます。

📁 出力先の制御 ⭐ NEW！

output_path パラメーターで生成画像の保存先を制御します。

3 つの動作モード：

1. 特定のファイルパス - 指定したファイルの場所に保存します。

generate_image(
    prompt="A beautiful sunset",
    output_path="/path/to/sunset.png"  # Exact file location
)

2. ディレクトリパス - 指定したディレクトリ内に自動生成されたファイル名で保存します。

generate_image(
    prompt="Product photo",
    output_path="/path/to/products/"  # Trailing slash indicates directory
)

3. デフォルトの場所 - IMAGE_OUTPUT_DIR または ~/nanobanana-images を使用します。

generate_image(
    prompt="Random image"
    # output_path defaults to None
)

複数の画像（n > 1）： ファイルパスを指定して複数の画像を生成すると、画像に自動で連番が付けられます。

• 1 枚目の画像：/path/to/image.png
• 2 枚目の画像：/path/to/image_2.png
• 3 枚目の画像：/path/to/image_3.png

優先順位のルール：

1. output_path パラメーター（指定されている場合） - 最優先
2. IMAGE_OUTPUT_DIR 環境変数
3. ~/nanobanana-images（デフォルトのフォールバック）

IMAGE_OUTPUT_DIR は output_path が省略された場合にのみ使用されます。images/sunset.png のような相対パスの output_path は、IMAGE_OUTPUT_DIR ではなく、サーバープロセスの作業ディレクトリを基準に解決されます。~/... はホームディレクトリに展開されます。末尾にスラッシュを付けると、ディレクトリがまだ存在しない場合（outputs/）でもディレクトリモードが選択され、サーバーがディレクトリを作成してファイル名を生成します。

# Save to specific location with Pro model
generate_image(
    prompt="Professional headshot",
    model_tier="pro",
    output_path="/Users/me/photos/headshot.png"
)

# Save multiple images to a directory
generate_image(
    prompt="Product variations",
    n=4,
    output_path="/path/to/products/"  # Each gets unique filename
)

⚙️ 環境変数

設定オプション：

# Authentication (Required)
# Method 1: API Key
GEMINI_API_KEY=your-gemini-api-key-here

# Method 2: Vertex AI (Google Cloud)
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=global  # Required for gemini-3-pro-image-preview and NB2; use "us-central1" only for legacy 2.5 Flash Image

# Model Selection (optional)
NANOBANANA_MODEL=auto  # Options: flash, nb2, pro, auto (default: auto → nb2)

# Optional
IMAGE_OUTPUT_DIR=/path/to/image/directory  # Default: ~/nanobanana-images
GEMINI_BASE_URL=https://custom-api.example.com  # Custom API endpoint (for proxies/gateways)
LOG_LEVEL=INFO                             # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=standard                        # standard, json, detailed

🐛 トラブルシューティング

よくある問題

「GEMINI_API_KEY not set」

• クライアントの MCP サーバー設定に API キーを追加してください。
• Google AI Studio で無料の API キーを取得してください。

「Server failed to start」

• 最新バージョンを使用していることを確認してください：uvx nanobanana-mcp-server@latest
• クライアントが MCP に対応していることを確認してください（Claude Desktop 0.10.0 以降）。

「Permission denied」エラー

• サーバーはデフォルトで ~/nanobanana-images に画像を作成します。
• ホームディレクトリへの書き込み権限があることを確認してください。

開発環境のセットアップ

ローカル開発の場合：

# Clone repository
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server

# Install with uv
uv sync

# Set environment
export GEMINI_API_KEY=your-api-key-here

# Run locally
uv run python -m nanobanana_mcp_server.server

📄 ライセンス

MIT License - 詳細は LICENSE をご覧ください。

🆘 サポート

• 課題：GitHub Issues
• ディスカッション：GitHub Discussions