Nanobanana MCP Server

Nano Banana MCP服务器🍌

生产准备就绪 模型上下文协议（MCP） 通过谷歌提供人工智能图像生成功能的服务器 双子座 具有智能模型选择的模型。

⭐ 新产品：纳米香蕉2——双子座3.1闪光图像！ 🍌🚀

纳米香蕉2 (gemini-3.1-flash-image-preview)现在是 默认模型 --以Flash速度提供专业级质量：

• 🍌 闪光速度+4K质量：Gemini 2.5 Flash延迟时高达3840px
• 🌐 谷歌搜索暂停：真实世界的知识，以获得真实准确的图像
• 🎯 主题一致性：每个场景最多5个角色和14个对象
• ✍️ 精确文本渲染：图像中清晰的文本位置
• 🏆 Gemini 3 Pro图片 仍然可以获得最大的推理深度

✨ 特性

• 🎨 多模型人工智能图像生成：三款具有智能自动选择功能的Gemini型号
• 🍌 双子座3.1闪光图像（NB2）：默认型号——4K分辨率，Flash速度，接地
• 🏆 Gemini 3 Pro图片：对最复杂的作文进行最大程度的推理
• ⚡ Gemini 2.5闪光图像：用于大批量快速原型制作的传统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注册表（推荐） 此服务器在 模型上下文协议注册表。搜索“nanobanana”或在您的MCP客户端上使用下面的MCP名称。

mcp名称：io.github.zhongweili/nanobanana-mcp服务器

选项2：使用 uvx

uvx nanobanana-mcp-server@latest

选项3：使用 pip

pip install nanobanana-mcp-server

🔧 配置

身份验证方法

Nano Banana支持两种身份验证方法 NANOBANANA_AUTH_METHOD:

1. API密钥 (api_key)：用途 GEMINI_API_KEY最适合本地开发和简单部署。
2. 顶点AI ADC (vertex_ai)：使用Google Cloud应用程序默认凭据。最适合在谷歌云（Cloud Run、GKE、GCE）上生产。
3. 自动 (auto)：如果存在，则默认为API键，否则尝试Vertex AI。

1.API密钥认证（默认）

集 GEMINI_API_KEY 环境变量。

2.顶点AI身份验证（谷歌云）

所需的环境变量：

• NANOBANANA_AUTH_METHOD=vertex_ai （或 auto)
• GCP_PROJECT_ID=your-project-id
• GCP_REGION=global （默认设置；Gemini 3 Pro Image和NB2是必需的。使用 us-central1 仅适用于传统的2.5 Flash Image型号。)

先决条件:

• 启用Vertex AI API： gcloud services enable aiplatform.googleapis.com
• 授予IAM角色： roles/aiplatform.user 到服务帐户。

克劳德桌面版

选项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：使用顶点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
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

克劳德代码（VS代码扩展）

在VS代码中安装和配置：

1. 安装Claude Code扩展
2. 打开命令选项板(Cmd/Ctrl + Shift + P)
3. 运行“克劳德代码：添加MCP服务器”
4. 配置：

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

光标

添加到Cursor的MCP配置：

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

OpenAI 代码专家

添加 ~/.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 直接在您的编码会话中使用工具。

备注：Codex配置文件由CLI和IDE扩展共享。TOML语法错误会同时破坏两者，因此请仔细验证您的编辑。

Continue.dev（VS代码/JetBrains）

添加到您的 config.json:

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

开放网页界面

在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--纳米香蕉2（双子座3.1闪光图像）⭐ 默认

闪光速度与专业级质量——两全其美

• 质量：生产就绪4K输出
• 决心：最高4K（3840px）
• 速度：每张图像约2-4秒（Flash类延迟）
• 特别功能:

- 🌐 谷歌搜索暂停：真实世界的知识，以获得真实准确的图像 - 🎯 主题一致性：每个场景最多5个角色和14个对象 - ✍️ 精确文本渲染：图像中清晰、位置正确的文本

• 最适合：几乎所有东西——制作资产、营销、摄影、文字叠加
• 模型层: "nb2" （或 "auto" --NB2为自动默认值）

🏆 Pro型号——Nano Banana Pro（Gemini 3 Pro图片）

为要求最苛刻的作文提供最大的推理深度

• 质量：最高可用
• 决心：最高4K（3840px）
• 速度：每张图片约5-8秒
• 特别功能:

- 🧠 高级推理：可配置的思维水平（低/高） - 🌐 谷歌搜索暂停：现实世界的知识整合 - 📐 媒体分辨率控制：微调视觉处理细节

• 最适合：复杂的叙事场景，错综复杂的构图，需要最大限度的推理
• 模型层: "pro"

⚡ 闪光灯型号（Gemini 2.5闪光灯图像）

大容量快速迭代的遗留模型

• 速度：非常快（2-3秒）
• 决心：高达1024px
• 最适合：大容量生成，不需要4K的快速草稿
• 模型层: "flash"

🤖 自动选择（推荐）

默认情况下，服务器使用 自动 路线模式 NB2 除非明显需要Pro更深入的推理：

选择Pro型号时:

• 强质量关键词：“4K”、“专业”、“制作”、“高分辨率”、“高清”
• 要求高思维水平： 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 -Square（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
)

1. 目录路径 -在特定目录中使用自动生成的文件名：

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

1. 默认位置 -使用IMAGE_OUTPUT_DIR或~/nanobanana图像：

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 （默认回退）

# 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”

• 将API密钥添加到客户端的MCP服务器配置中
• 在获取免费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许可证-请参阅 许可证 了解详情。

🆘 支持

• 问题:
• 讨论: