使用说明

克劳德纳米香蕉mcp

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

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

生成	编辑	多编辑	超宽

文本到图像	单镜头编辑	迭代会话	21:9电影

快速开始

先决条件

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

工具

工具	用途	API调用	说明
`nanobanana_generate_image`	文本到图像	是	根据文本描述生成新图像
`nanobanana_edit_image`	编辑图像	是	使用文本指令修改现有图像
`nanobanana_multi_edit_start`	开始会话	是	开始迭代编辑会话（从文本或图像）
`nanobanana_multi_edit_continue`	继续会话	是	在活动会话中应用下一次编辑
`nanobanana_multi_edit_end`	结束会话	否	关闭会话并释放内存
`nanobanana_list_sessions`	列出会话	否	显示所有活动的编辑会话
`nanobanana_list_options`	列出选项	否	显示型号、参数和兼容性

何时使用哪种工具

用户请求	工具
“画一只猫”/“生成日落”	`generate_image`
“将这张照片黑白化”（带文件）	`edit_image`
“让我们一步一步地设计一个标志”	`multi_edit_start` → `continue` → `end`
“有哪些型号可供选择？”	`list_options`

用法示例

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

"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个字符）

模型比较

功能	纳米香蕉2	纳米香蕉Pro
型号ID	`gemini-3.1-flash-image-preview`	`gemini-3-pro-image-preview`
速度	快	慢，质量更高
第512号决议	是	否
可配置思维	是（最小/高）	否（始终打开）
图像搜索基础	是	否
纵横比	全部14	9（没有1:4、1:8、4:1、8:1、21:9）
最大参考图像数	14	11

如何选择

场景	推荐模型
快速草稿、缩略图、迭代	Nano Banana 2
大批量生产	纳米香蕉2
复杂成分	纳米香蕉Pro
忠实的文本渲染	Nano Banana Pro
逼真的场景	Nano Banana Pro
极端宽高比（全景、高横幅）	Nano Banana 2

参数

公共参数

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

参数	值	默认值	注释
`model`	`gemini-3.1-flash-image-preview`, `gemini-3-pro-image-preview`	NB2	参见模型差异
`aspect_ratio`	14个选项（NB2）/9个选项（Pro）	`1:1`	请参阅宽高比
`image_size`	`512`, `1K`, `2K`, `4K`	`1K`	512=NB2。区分大小写（使用 `1K` 不 `1k`)
`thinking_level`	`minimal`, `High`	`minimal`	高=仅NB2。Pro具有内置思维
`enable_search`	`true`, `false`	`false`	谷歌搜索为真实世界的准确性奠定了基础
`enable_image_search`	`true`, `false`	`false`	图像搜索基础（仅限NB2）
`response_format`	`markdown`, `json`	`markdown`	文本部分的输出格式

工具特定参数

参数	工具	类型	必填
`prompt`	`generate_image`, `multi_edit_start`	string	是
`edit_instruction`	`edit_image`, `multi_edit_continue`	string	是
`source_image_path`	`edit_image`	string	是
`source_image_path`	`multi_edit_start`	string	否（对于文本到图像省略）
`session_id`	`multi_edit_continue`, `multi_edit_end`	string	是

宽高比

比率	用例	NB2	Pro
`1:1`	徽标、图标、头像、社交媒体	是	是
`2:3`	肖像照片	是	是
`3:2`	风景照片	是	是
`3:4`	肖像，书籍封面	是	是
`4:3`	经典景观，展示	是	是
`4:5`	Instagram帖子	是	是
`5:4`	稍宽的静物	是	是
`9:16`	手机壁纸、故事、卷轴	是	是
`16:9`	桌面壁纸，YouTube缩略图	是	是
`1:4`	高横幅、书签	是	否
`1:8`	极端垂直	是	否
`4:1`	宽横幅	是	否
`8:1`	超宽全景	是	否
`21:9`	超广角电影	是	否

自动推理

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

用户说	克劳德推断
“手机壁纸”	`aspect_ratio: "9:16"`
“桌面壁纸”	`aspect_ratio: "16:9"`
“YouTube缩略图”	`aspect_ratio: "16:9"`, `image_size: "2K"`
“Instagram帖子”	`aspect_ratio: "4:5"`
“徽标”/“图标”/“头像”	`aspect_ratio: "1:1"`
“超宽”/“电影级”	`aspect_ratio: "21:9"`
“印刷海报”/“高分辨率”	`image_size: "4K"`
“快速草稿”/“缩略图”	`image_size: "512"`
“复杂场景”/“详细”	`thinking_level: "High"`
真实地点/时事	`enable_search: true`
视觉风格参考	`enable_image_search: true`
文本渲染/照片级真实感	`model: Pro`

快速指南

黄金法则

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

提示模板

模板来源于谷歌官方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 查看包含每个测试结果的完整报告。

度量	值
测试用例总数	65
通过	63
发现已知API限制	2（已修复）
测试覆盖率	100%的参数、模型和主要场景
API调用总数	~80

故障排除

问题	解决方案
`GEMINI_API_KEY environment variable is not set`	确保密钥通过 `-e GEMINI_API_KEY=...` 在 `claude mcp add` 命令
`Failed to connect` 在 `claude mcp list`	验证路径 `dist/index.js` 是正确的 `npm run build` 已运行
注册后未显示工具	重新启动Claude Code会话（退出并重新输入）
`Image size "512" is only available with Nano Banana 2`	切换到模型 `gemini-3.1-flash-image-preview` 或使用1K/2K/4K
`Aspect ratio "X" is not supported by Nano Banana Pro`	Pro仅支持9个比率。切换到NB2以获得极端比率（1:4、1:8、4:1、8:1、21:9）
`Thinking level "High" is only configurable on Nano Banana 2`	Pro具有内在的思考能力。如果你需要明确的高思维，请使用NB2
`Image file not found`	提供源图像的绝对路径
`Unsupported image format`	支持：.png、.jpg、.jpeg、.webp、.gif
`Session not found`	会话可能已过期（超时30分钟）。开始一个新的
`fetch failed`	瞬态网络错误。重试请求

使用克劳德代码构建

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

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

许可证

麻省理工学院