Nanobanana Mcp Server

Nano Banana MCP 服务 🍌

一个可用于生产环境的 Model Context Protocol（MCP） 服务，通过 Google 的 Gemini 模型提供 AI 图像生成功能，并能智能选择模型。

⭐ 新功能：Nano Banana 2 — Gemini 3.1 Flash Image！🍌🚀

Nano Banana 2（gemini-3.1-flash-image-preview）现已成为默认模型，以 Flash 的速度提供 Pro 级质量：

• 🍌 Flash 速度 + 4K 画质：最高可达 3840px，延迟与 Gemini 2.5 Flash 相当
• 🌐 Google Search Grounding：借助现实世界知识生成事实准确的图像
• 🎯 主体一致性：每个场景最多可包含 5 个角色和 14 个物体
• ✍️ 精准文本渲染：在图像中清晰准确地放置文本
• 🏆 仍可使用 Gemini 3 Pro Image，获得最强推理能力

✨ 功能特性

• 🎨 多模型 AI 图像生成：提供三种 Gemini 模型，并能智能自动选择
• 🍌 Gemini 3.1 Flash Image（NB2）：默认模型，以 Flash 速度生成 4K 分辨率图像，并支持 grounding
• 🏆 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 支持两种身份验证方式：

1. API Key（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 Key，则默认使用；否则尝试使用 Vertex AI。

1. API Key 身份验证（默认）

设置 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）

若要使用 Google Cloud 应用默认凭据进行身份验证（而不是使用 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": "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 的 CLI 和 VSCode 扩展使用同一个 config.toml。添加后，Codex 可在编码会话中直接调用 generate_image、edit_image 和 upload_file 工具。

注意：CLI 和 IDE 扩展共用 Codex 配置文件。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 支持三种 Gemini 模型，并可智能自动选择：

🍌 NB2 — Nano Banana 2（Gemini 3.1 Flash Image）⭐ 默认

Flash 级速度，Pro 级质量——兼得两全

• 质量：可用于生产环境的 4K 输出
• 分辨率：最高 4K（3840px）
• 速度：每张图片约 2-4 秒（Flash 级延迟）
• 特色功能：
  • 🌐 Google 搜索增强：利用现实世界知识生成事实准确的图片
  • 🎯 主体一致性：每个场景最多支持 5 个角色和 14 个物体
  • ✍️ 精准文本渲染：在图片中清晰地放置文本
• 适用场景：几乎所有场景——生产素材、营销、摄影、文本叠加
• model_tier："nb2"（或 "auto"——NB2 是自动模式的默认模型）

🏆 Pro 模型 — Nano Banana Pro（Gemini 3 Pro Image）

为要求最高的构图提供最深入的推理

• 质量：当前可用的最高质量
• 分辨率：最高 4K（3840px）
• 速度：每张图片约 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”、“专业”、“生产”、“高分辨率”、“HD”
• 请求较高的思考级别：thinking_level="HIGH"
• 使用多张输入图片进行多图条件控制

选择 NB2 模型的情况（默认）：

• 常规请求、日常图片生成
• 强调速度的关键词：“快速”、“草稿”、“素描”、“迅速”
• 高频批量生成（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"。

📁 输出路径控制 ⭐ 全新！

使用 output_path 参数控制生成图像的保存位置：

三种操作模式：

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）： 使用文件路径生成多张图像时，图像会自动编号：

• 第一张图像：/path/to/image.png
• 第二张图像：/path/to/image_2.png
• 第三张图像：/path/to/image_3.png

优先级规则：

1. output_path 参数（若已提供）- 最高优先级
2. IMAGE_OUTPUT_DIR 环境变量
3. ~/nanobanana-images（默认回退路径）

仅当省略 output_path 时才会使用 IMAGE_OUTPUT_DIR。相对路径 output_path（例如 images/sunset.png）会相对于服务进程的工作目录解析，而不是相对于 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 未设置”

• 在客户端的 MCP 服务配置中添加 API 密钥
• 在 Google AI Studio 获取免费 API 密钥

“服务启动失败”

• 确保使用的是最新版本：uvx nanobanana-mcp-server@latest
• 检查客户端是否支持 MCP（Claude Desktop 0.10.0+）

“权限被拒绝”错误

• 服务默认会在 ~/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。

🆘 支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions