Claude Nanobanana MCP

克劳德纳米香蕉mcp

MCP服务器，用于通过谷歌的Nano Banana（Gemini image）API生成和编辑人工智能图像。提供7个工具，让Claude Code从文本生成图像、编辑现有图像和运行多轮迭代优化会话。

该项目完全由以下人员开发、调试和测试 克劳德代码 （克劳德作品4.6）。没有人类编写的代码。

快速开始

先决条件

• Node.js 18+
• Gemini API密钥 --免费从 谷歌人工智能工作室

安装

git clone https://github.com/1439616687/claude-nanobanana-mcp.git
cd claude-nanobanana-mcp
npm install
npm run build

在克劳德代码中注册

用户范围 （适用于所有项目）：

claude mcp add nanobanana --scope user \
  -e GEMINI_API_KEY=your-key-here \
  -- node /absolute/path/to/claude-nanobanana-mcp/dist/index.js

局部作用域 （仅限当前项目）：

claude mcp add nanobanana \
  -e GEMINI_API_KEY=your-key-here \
  -- node /absolute/path/to/claude-nanobanana-mcp/dist/index.js

替换 /absolute/path/to/ 使用克隆仓库的实际路径。

验证

在注册之后， 重新启动Claude Code会话，然后问：

What image generation tools are available?

克劳德应该用7个纳米香蕉工具来回应。如果没有，运行 claude mcp list 检查连接状态。

卸载

claude mcp remove nanobanana          # local scope
claude mcp remove nanobanana --scope user  # user scope

工具

何时使用哪种工具

用法示例

用自然语言告诉克劳德你想要什么：

"Draw a cartoon cat wearing a top hat as a phone wallpaper"
  → Claude auto-infers: generate_image, aspect_ratio 9:16, NB2

"Change this image to look like an oil painting"
  → Claude uses: edit_image with source_image_path

"I want to design a coffee shop logo, let's iterate"
  → Claude starts: multi_edit_start, then continue for each round

"Make it a 4K print poster with a cinematic feel"
  → Claude auto-infers: image_size 4K, aspect_ratio 21:9

模型

纳米香蕉2(gemini-3.1-flash-image-preview)

快速、多功能的型号。最适合大多数用例。

• 4个分辨率级别：512、1K、2K、4K
• 所有14个纵横比
• 可配置思维（最小/高）
• 谷歌搜索+图片搜索基础
• 最多14个参考图像（10个对象+4个字符）

纳米香蕉Pro(gemini-3-pro-image-preview)

复杂构图和忠实文本渲染的高级模型。

• 3个分辨率级别：1K、2K、4K（无512）
• 9个纵横比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9
• 内置的持续思考（不可配置）
• 仅限谷歌搜索（无图片搜索）
• 最多11个参考图像（6个对象+5个字符）

模型比较

如何选择

参数

公共参数

所有生成和编辑工具都共享这些参数：

工具特定参数

宽高比

自动推理

Claude会自动从上下文中选择最佳参数——您不需要手动指定它们：

快速指南

黄金法则

将场景描述为叙述性段落，而不是关键字列表。 该模型的核心优势在于对语言的深入理解。描述性段落总是比不连贯的单词产生更好的结果。

提示模板

模板来源于 谷歌官方Gemini图像生成文档.

Claude为常见类别提供了内置模板。您也可以直接使用这些：

照片级真实感：

A photorealistic [shot type] of [subject], [action/expression], set in [environment].
Illuminated by [lighting], creating a [mood] atmosphere.
Captured with a [camera/lens], emphasizing [key textures/details].

贴纸/图标：

A [style] sticker of [subject], featuring [characteristics] and a [color palette].
The design has [line style] and [shading]. The background must be white.

产品/商业：

A photo of [product] on [surface]. [Lighting description].
[Brand/text integration details]. [Magazine/ad context if applicable].

信息图：

Create a [style] infographic explaining [topic] as [creative analogy].
Show [elements]. Style like [reference], suitable for [audience].

等距三维：

A 45 degree top-down isometric miniature 3D [style] scene of [location],
featuring [landmarks/elements]. Soft refined textures with PBR materials
and gentle lighting. [Title text] in bold at top-center.

科学/技术：

[Artist/style reference] style [illustration type] of [subject].
Detailed drawings of [components] on [medium texture] with notes in [language].

文本/排版：

[Format] with the text "[exact text]" in [font style].
[Placement and sizing details]. [Additional design elements].

编辑模板

风格转换： Convert this to [style] with [specific characteristics]

背景更改： Replace the background with [environment], keeping the [subject] unchanged

对象添加/删除： Add [object] at [position] / Remove [object] and fill naturally

本地化： Update this to be in [language]. Do not change any other elements.

品牌整合： Put this logo on [product/context]. The logo is perfectly integrated into [surface].

重要说明

• 不支持透明背景 --使用“白色背景”或纯色
• 对于文本呈现，要明确准确的文本内容、字体样式、位置和大小
• 对于贴纸/图标，始终指定“背景必须是白色的”
• Claude可以通过结合9步策略来处理这些模板之外的请求：主题、设置、照明、风格、构图、情绪、相机、调色板、文本

输出

生成的图像保存到 nanobanana-output/ 在当前工作目录中。

文件名使用以下格式 {timestamp}-{random}.png例如。， 1711929600000-a3f2.png.

支持的编辑输入格式：PNG、JPEG、WebP、GIF。

建筑

src/
├── index.ts              # MCP server init, 7 tool registrations, StdioServerTransport
├── types.ts              # All TypeScript interfaces (Gemini API types, session state, tool results)
├── constants.ts          # Model IDs, enums, defaults, compatibility table
├── schemas/
│   └── tool-schemas.ts   # Zod schemas with Google prompt templates in .describe()
├── services/
│   ├── gemini-client.ts  # HTTP client for Gemini REST API (generate, edit, multiTurn)
│   ├── image-handler.ts  # Read/write images to disk as base64, MIME detection
│   ├── session-manager.ts# In-memory session store (Map) with 30min auto-expiry
│   └── shared-utils.ts   # Parameter validation (5 rules), config builders, response extraction
└── tools/
    ├── generate.ts       # nanobanana_generate_image handler
    ├── edit.ts           # nanobanana_edit_image handler
    ├── multi-edit.ts     # multi_edit_start/continue/end handlers
    └── info.ts           # list_sessions, list_options handlers

关键设计决策

• 原始获取而不是SDK --完全控制请求整形，否 @google/genai 依赖
• 思想签名保存 --多回合会话存储所有模型响应部分（包括 thoughtSignature 令牌），以实现最佳API连续性
• 会话安全错误处理 -只有在API响应成功后，用户回合才会附加到会话历史记录中，以防止失败时的会话损坏
• 模式中嵌入的Google提示模板 --Claude Code通过Zod在每次工具调用中都能看到模板 .describe() 领域

测试

与平行的代理团队在4轮比赛中进行了全面的测试。看 tests/TESTING.md 查看包含每个测试结果的完整报告。

故障排除

使用克劳德代码构建

整个项目是通过人工智能协作创建的，使用 克劳德代码 （克劳德作品4.6）：

• 架构与实施：从头开始设计和编码——12个TypeScript源文件，约1500行
• 代码审查和Bug修复：识别并修复了7个错误，包括会话损坏、API字段命名不匹配（camelBase与snake_case）和过早的思想部分过滤
• API验证：通过系统测试发现2个未记录的Gemini API约束（Pro不支持高思考或极端纵横比）
• 提示工程：将谷歌的官方提示模板直接集成到工具模式中
• 测试：通过模拟临时用户、高级用户和设计师的并行代理团队执行65个测试用例
• 文档：Claude编写的所有文档，根据谷歌官方Gemini API文档进行验证

许可证

麻省理工学院