金大哥 - nanobanana-mcp-server MCP 详情

article

README

🚀 纳米香蕉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资源浏览模板和文件元数据
🛡️ 生产就绪：具备全面的错误处理、日志记录和验证功能
⚡ 高性能：采用智能缓存的优化架构

🚀 快速开始

前提条件

谷歌Gemini API密钥 - 在此免费获取
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进行两种认证方法：

API密钥 (api_key)：使用GEMINI_API_KEY。适用于本地开发和简单部署。
Vertex AI ADC (vertex_ai)：使用谷歌云应用默认凭证。适用于谷歌云（Cloud Run、GKE、GCE）上的生产环境。
自动 (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中安装并配置：

安装Claude代码扩展
打开命令面板 (Cmd/Ctrl + Shift + P)
运行“Claude代码：添加MCP服务器”
进行配置：

{
  "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讨论

nanobanana-mcp-server