Nanobanana MCP Server

🚀 納米香蕉MCP服務器 🍌

納米香蕉MCP服務器是一個可用於生產環境的模型上下文協議（MCP） 服務器，它藉助谷歌的Gemini模型，通過智能模型選擇，提供由人工智能驅動的圖像生成能力。

⭐ 新特性：支持Gemini 3 Pro圖像！🚀

現在推出了納米香蕉專業版 —— 谷歌最新、功能最強大的圖像生成模型：

• 🏆 專業4K畫質：可生成分辨率高達3840px的驚豔圖像
• 🌐 谷歌搜索關聯：利用現實世界的知識，生成事實準確的圖像
• 🧠 高級推理：可配置思維級別，用於複雜構圖
• 🎯 卓越的文本渲染：高分辨率下圖像中的文本清晰銳利
• 🎨 增強的理解能力：更好地理解複雜提示的上下文

✨ 主要特性

• 🎨 多模型AI圖像生成：可在快速版（速度優先）和專業版（質量優先）模型之間進行智能選擇
• ⚡ Gemini 2.5快速圖像：快速生成（1024px），適用於快速原型製作
• 🏆 Gemini 3 Pro圖像：支持高達4K的高質量圖像，具備谷歌搜索關聯功能
• 🤖 智能模型選擇：根據你的提示自動選擇最佳模型
• 📐 寬高比控制 ⭐ 新特性：可指定輸出尺寸（1:1、16:9、9:16、21:9等）
• 📋 智能模板：為攝影、設計和編輯提供預建的提示模板
• 📁 文件管理：通過Gemini文件API上傳和管理文件
• 🔍 資源發現：通過MCP資源瀏覽模板和文件元數據
• 🛡️ 生產就緒：具備全面的錯誤處理、日誌記錄和驗證功能
• ⚡ 高性能：採用智能緩存的優化架構

🚀 快速開始

前提條件

1. 谷歌Gemini API密鑰 - 在此免費獲取
2. Python 3.11+（僅用於開發）

安裝

選項1：從MCP註冊表安裝（推薦） 此服務器可在模型上下文協議註冊表中找到。搜索“nanobanana”，或在你的MCP客戶端中使用以下MCP名稱。 MCP名稱：io.github.zhongweili/nanobanana-mcp-server

選項2：使用uvx安裝

uvx nanobanana-mcp-server@latest

選項3：使用pip安裝

pip install nanobanana-mcp-server

🔧 配置

認證方法

納米香蕉支持通過NANOBANANA_AUTH_METHOD進行兩種認證方法：

1. API密鑰 (api_key)：使用GEMINI_API_KEY。適用於本地開發和簡單部署。
2. Vertex AI ADC (vertex_ai)：使用谷歌雲應用默認憑證。適用於谷歌雲（Cloud Run、GKE、GCE）上的生產環境。
3. 自動 (auto)：如果存在API密鑰，則默認使用API密鑰，否則嘗試使用Vertex AI。

1. API密鑰認證（默認）

設置GEMINI_API_KEY環境變量。

2. Vertex AI認證（谷歌雲）

需要設置的環境變量：

• NANOBANANA_AUTH_METHOD=vertex_ai（或auto）
• GCP_PROJECT_ID=your-project-id
• GCP_REGION=us-central1（默認）

前提條件：

• 啟用Vertex AI API：gcloud services enable aiplatform.googleapis.com
• 為服務賬戶授予IAM角色：roles/aiplatform.user

Claude桌面端

選項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密鑰）：

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

配置文件位置：

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

Claude代碼（VS Code擴展）

在VS Code中安裝並配置：

1. 安裝Claude代碼擴展
2. 打開命令面板 (Cmd/Ctrl + Shift + P)
3. 運行“Claude代碼：添加MCP服務器”
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"
      }
    }
  }
}

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

打開Web UI

在Open WebUI設置中進行配置：

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

Gemini CLI / 通用MCP客戶端

# 設置環境變量
export GEMINI_API_KEY="your-gemini-api-key-here"

# 以標準輸入輸出模式運行服務器
uvx nanobanana-mcp-server@latest

# 或者通過pip安裝後運行
python -m nanobanana_mcp_server.server

🤖 模型選擇

納米香蕉支持兩種Gemini模型，並具備智能自動選擇功能：

🏆 專業版模型 - 納米香蕉專業版（Gemini 3 Pro圖像） ⭐ 新特性！

谷歌最新、最先進的圖像生成模型

• 質量：專業級，可用於生產環境
• 分辨率：最高可達4K（3840px） - 現有最高分辨率
• 速度：每張圖像約5 - 8秒
• 特殊功能：
  • 🌐 谷歌搜索關聯：利用現實世界的知識，生成準確、有上下文的圖像
  • 🧠 高級推理：可配置思維級別（低/高），用於複雜構圖
  • 📐 媒體分辨率控制：微調視覺處理細節（低/中/高/自動）
  • 📝 卓越的文本渲染：在圖像生成中，文本清晰度極高
  • 🎨 增強的上下文理解：更好地解讀複雜的敘述性提示
• 適用場景：生產素材、營銷材料、專業攝影、高保真輸出、需要文本的圖像、事實準確的圖像
• 成本：每張圖像成本較高（優質品質）

⚡ 快速版模型（Gemini 2.5快速圖像）

用於快速迭代的快速、可靠模型

• 速度：非常快（2 - 3秒）
• 分辨率：最高可達1024px
• 質量：日常使用的高質量圖像
• 適用場景：快速原型製作、迭代、大批量生成、草稿、草圖
• 成本：每張圖像成本較低

🤖 自動選擇（推薦）

默認情況下，服務器使用自動模式，該模式會智能分析你的提示和需求：

選擇專業版模型的情況：

• 檢測到質量關鍵詞：“4K”、“專業”、“生產”、“高分辨率”、“高清”
• 請求高分辨率：resolution="4k" 或 resolution="high"
• 啟用谷歌搜索關聯：enable_grounding=True
• 請求高思維級別：thinking_level="HIGH"
• 多圖像條件處理，包含多個輸入圖像

選擇快速版模型的情況：

• 檢測到速度關鍵詞：“快速”、“草稿”、“草圖”、“快速迭代”
• 大批量生成：n > 2
• 請求標準或較低分辨率
• 不需要專業版的特殊功能

💻 使用示例

基礎用法

# 自動選擇（推薦）
"Generate a professional 4K product photo"  # → 專業版模型（質量關鍵詞 + 4K）
"Quick sketch of a cat"                     # → 快速版模型（速度關鍵詞）
"Create a diagram with clear text labels"   # → 專業版模型（文本渲染）
"Draft mockup for website hero section"     # → 快速版模型（草稿關鍵詞）

# 顯式模型選擇
generate_image(
    prompt="A scenic landscape",
    model_tier="flash"  # 強制使用快速版模型以提高速度
)

# 利用納米香蕉專業版特性
generate_image(
    prompt="Professional product photo of vintage camera on wooden desk",
    model_tier="pro",              # 使用專業版模型
    resolution="4k",               # 4K分辨率（僅專業版支持）
    thinking_level="HIGH",         # 增強推理
    enable_grounding=True,         # 使用谷歌搜索以確保準確性
    media_resolution="HIGH"        # 高細節視覺處理
)

# 專業版模型用於高質量文本渲染
generate_image(
    prompt="Infographic showing 2024 market statistics with clear labels",
    model_tier="pro",              # 專業版在文本渲染方面表現出色
    resolution="4k"                # 文本清晰度最高
)

# 控制不同格式的寬高比 ⭐ 新特性！
generate_image(
    prompt="Cinematic landscape at sunset",
    aspect_ratio="21:9"            # 超寬電影格式
)

generate_image(
    prompt="Instagram post about coffee",
    aspect_ratio="1:1"             # 社交媒體的方形格式
)

generate_image(
    prompt="YouTube thumbnail design",
    aspect_ratio="16:9"            # 標準視頻格式
)

generate_image(
    prompt="Mobile wallpaper of mountain vista",
    aspect_ratio="9:16"            # 手機的豎屏格式
)

高級用法

# 不同用例的寬高比示例
generate_image(
    prompt="Product showcase for e-commerce",
    aspect_ratio="3:4",    # 豎屏格式，適用於產品頁面
    model_tier="pro"
)

generate_image(
    prompt="Social media banner for Facebook",
    aspect_ratio="16:9"    # 橫向橫幅格式
)

注意：寬高比控制適用於快速版和專業版模型。若要在特定寬高比和高分辨率下獲得最佳效果，請使用專業版模型並設置resolution="4k"。

⚙️ 環境變量

配置選項：

# 認證（必需）
# 方法1：API密鑰
GEMINI_API_KEY=your-gemini-api-key-here

# 方法2：Vertex AI（谷歌雲）
NANOBANANA_AUTH_METHOD=vertex_ai
GCP_PROJECT_ID=your-project-id
GCP_REGION=us-central1

# 模型選擇（可選）
NANOBANANA_MODEL=auto  # 選項：flash、pro、auto（默認：auto）

# 可選
IMAGE_OUTPUT_DIR=/path/to/image/directory  # 默認：~/nanobanana-images
LOG_LEVEL=INFO                             # DEBUG、INFO、WARNING、ERROR
LOG_FORMAT=standard                        # standard、json、detailed

🐛 故障排除

常見問題

“GEMINI_API_KEY未設置”

• 將你的API密鑰添加到客戶端的MCP服務器配置中
• 在谷歌AI工作室獲取免費的API密鑰

“服務器啟動失敗”

• 確保使用的是最新版本：uvx nanobanana-mcp-server@latest
• 檢查你的客戶端是否支持MCP（Claude桌面端0.10.0+）

“權限被拒絕”錯誤

• 服務器默認在~/nanobanana-images目錄下創建圖像
• 確保你對主目錄有寫入權限

開發設置

本地開發步驟：

# 克隆倉庫
git clone https://github.com/zhongweili/nanobanana-mcp-server.git
cd nanobanana-mcp-server

# 使用uv安裝
uv sync

# 設置環境變量
export GEMINI_API_KEY=your-api-key-here

# 本地運行
uv run python -m nanobanana_mcp_server.server

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

🆘 支持

• 問題反饋：GitHub問題
• 討論交流：GitHub討論