内容
# 纳米香蕉MCP
[](https://github.com/petrkindlmann/nano-banana-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
用于 **AI图像生成和编辑** 的模型上下文协议服务器，基于谷歌的Gemini "纳米香蕉" 图像模型，通过 [交互式API](https://ai.google.dev/gemini-api/docs/interactions/image-generation) 实现。
直接从Claude Code、Claude Desktop、Cursor或任何MCP兼容的客户端生成、编辑和迭代图像，支持多轮编辑、搜索基础、交叉故事板、风格一致的图标集和视频生成图像。
<p align="center">
<img src="docs/images/showcase-product.jpg" width="32%" alt="一款青绿色的陶瓷咖啡杯的照片级产品拍摄" />
<img src="docs/images/showcase-isometric.jpg" width="32%" alt="开发者工作站的等距插图" />
<img src="docs/images/showcase-sticker.png" width="32%" alt="戴着墨镜的卡哇伊香蕉贴纸" />
</p>
<p align="center"><em>所有图像均由该服务器生成 - 一个照片级产品拍摄、一个带有可读文本的等距插图和一个矢量贴纸。无需编辑。</em></p>
> **注意：** 该服务器使用Gemini **交互式API**，目前处于 **测试阶段**。Gemini 3图像模型（`gemini-3-pro-image`，`gemini-3.1-flash-image`）可能需要您的API密钥才能访问。`nano`层（`gemini-2.5-flash-image`）是最广泛可用的。请参见 [要求](#要求)。
## 功能
- **文本转图像** - 根据提示生成高质量的图像，最高可达4K，支持宽高比和分辨率控制
- **多轮编辑** - 会话式迭代；每次结果返回一个`interaction_id`，您可以将其传回以继续编辑
- **参考图像** - 最多14个输入用于虚拟试穿、产品摆放、合成、风格转换、照片修复、属性替换、2D→3D模型
- **搜索基础** - 使用谷歌搜索和谷歌图像搜索实时基础图像
- **交叉故事** - 一个提示 → 一个图像序列（故事板、漫画、食谱、图解说明）
- **风格一致的图标集** - 链式生成在图标集上保持统一外观
- **视频生成图像** - 从公开的YouTube网址生成缩略图/海报
- **内联预览** - 缩放预览返回给客户端，以便模型可以看到它生成的内容并自我纠正
- **健壮** - 自动重试和回退处理速率限制和暂时性错误；清晰、有效的错误消息
## 快速入门
### 1. 获取Gemini API密钥
在 [谷歌AI工作室](https://aistudio.google.com/apikey) 创建密钥。
### 2. 安装
```bash
git clone https://github.com/petrkindlmann/nano-banana-mcp.git
cd nano-banana-mcp
npm install
```
### 3. 在您的MCP客户端注册
#### Claude Code
```bash
claude mcp add nano-banana --scope user \
--env GEMINI_API_KEY=your_key_here \
-- node /absolute/path/to/nano-banana-mcp/index.js
```
#### Claude Desktop / Cursor / Windsurf / VS Code
在您的MCP配置中添加（例如 `~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上）：
```json
{
"mcpServers": {
"nano-banana": {
"command": "node",
"args": ["/absolute/path/to/nano-banana-mcp/index.js"],
"env": {
"GEMINI_API_KEY": "your_key_here"
}
}
}
}
```
重启您的客户端。下面将出现五个工具。
### 配置
| 环境变量 | 必需 | 描述 |
| --- | --- | --- |
| `GEMINI_API_KEY` | ✅ | 您的Gemini API密钥。 |
| `NANO_BANANA_MODEL_NANO` | — | 覆盖`nano`层的模型ID。 |
| `NANO_BANANA_MODEL_FLASH` | — | 覆盖`flash`层的模型ID。 |
| `NANO_BANANA_MODEL_PRO` | — | 覆盖`pro`层的模型ID。 |
模型ID是测试/预览模型，谷歌会定期更新和淘汰。如果发布了新版本 - 或者您配置的ID已弃用 - 请指向一个新的模型，而无需编辑代码：
```json
"env": {
"GEMINI_API_KEY": "your_key_here",
"NANO_BANANA_MODEL_FLASH": "gemini-3.2-flash-image"
}
```
每个层级保持其功能配置文件（尺寸、宽高比、基础），无论您为其分配的ID如何。
## 用法
只需用自然语言提问 - 您的MCP客户端会选择正确的工具和参数。
> **您：** 生成一个16:9的英雄图像，背景是雾气缭绕的松树林，黎明时分，电影般，保存为`hero.jpg`
>
> **Claude：** *调用`generate_image` → 保存`hero.jpg`，返回一个`interaction_id`和预览*
>
> **您：** 让雾气更浓并在林间空地上添加一只鹿
>
> **Claude：** *调用`edit_image`，使用之前的`interaction_id` → `hero-v2.jpg`*
多轮编辑是推荐的迭代方式：每次结果都会携带一个`interaction_id`，而将其传回可以保持完整的对话上下文，使编辑保持一致。
## 工具
| 工具 | 描述 |
| --- | --- |
| `generate_image` | 根据文本提示生成单个图像。可选的搜索基础、思考和宽高比/尺寸控制。 |
| `edit_image` | 编辑或迭代图像 - 通过`previous_interaction_id`进行链式调用，或从磁盘传递参考图像。 |
| `generate_story` | 根据一个提示生成交叉文本 + 图像（故事板、漫画、食谱、图解说明）。 |
| `generate_icon_set` | 通过链式生成生成一组风格一致的图标。 |
| `generate_from_video` | 根据公开的YouTube视频网址生成图像（仅限`flash`模型）。 |
### 模型
| 层级 | 模型ID | 尺寸 | 搜索基础 | 思考 | 视频输入 | JPEG输出 |
| --- | --- | --- | --- | --- | --- | --- |
| `nano` | `gemini-2.5-flash-image` | 1K | — | — | — | —（仅限PNG） |
| `flash` | `gemini-3.1-flash-image` | 0.5K, 1K, 2K, 4K | 网页 + 图像 | — | ✅ | ✅ |
| `pro` | `gemini-3-pro-image` | 1K, 2K, 4K | 网页 | ✅ | — | ✅ |
**我应该使用哪一个？**
- **`flash`（默认）- 您的首选。** 质量、成本和延迟的最佳平衡。最高可达4K，搜索基础，最宽的宽高比（`21:9`、`1:4`等）和唯一接受视频输入的层级。
- **`pro` - 最高质量的渲染器。** 用于专业/交付资产、复杂的多元素指令和图像中可读的**文本**（信息图表、海报、菜单）。内置的“思考”过程在渲染前优化构图。较慢且较贵。
- **`nano` - 速度和容量。** 仅限1K，无基础/思考，始终返回PNG。当快速生成许多图像且每张图像的质量不那么重要时，请使用它。
> `generate_story` 默认使用 `pro`（最佳交叉质量）；`generate_from_video` 锁定到 `flash`（唯一接受视频的层级）。
### `generate_image`
| 参数 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `prompt` | 字符串 | — | **必填。** 要生成的内容。 |
| `output` | 字符串 | — | **必填。** 输出文件路径。扩展名选择格式：`.png`（默认）或`.jpg`（仅限`flash`/`pro`）。 |
| `model` | `nano`/`flash`/`pro` | `flash` | 模型层级。 |
| `ratio` | 字符串 | `1:1` | 例如 `16:9`、`9:16`、`4:3`；`21:9`/`1:4`/`4:1`/`1:8`/`8:1` 仅限 `flash`。 |
| `size` | `0.5K`/`1K`/`2K`/`4K` | `1K` | `0.5K` 仅限 `flash`。 |
| `use_search` | 布尔值 | `false` | 使用谷歌搜索基础（`flash`/`pro`）。 |
| `use_image_search` | 布尔值 | `false` | 同时使用谷歌图像搜索作为视觉上下文（`flash`）。 |
| `show_thinking` | 布尔值 | `false` | 包括模型的思考总结（`pro`）。 |
| `preview` | 布尔值 | `true` | 返回小预览图像给客户端。 |
返回文件路径 **和** `interaction_id` - 将其传递给 `edit_image` 以继续迭代。
### `edit_image`
与 `generate_image` 相同的图像控件，加上：
| 参数 | 类型 | 备注 |
| --- | --- | --- |
| `previous_interaction_id` | 字符串 | 会话式继续之前的生成/编辑（推荐的迭代方式）。 |
| `reference_images` | 字符串[] | 磁盘上的参考图像路径（最多14个；`flash`：10个对象 + 4个字符，`pro`：6个 + 5个）。 |
### `generate_story`
| 参数 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `prompt` | 字符串 | — | **必填。** 例如：*“一个6面板的故事板，讲述一只狐狸学习飞行的故事，插图和字幕交织。”* |
| `output_dir` | 字符串 | — | **必填。** 编号图像的目录。 |
| `basename` | 字符串 | `story` | 文件名前缀。 |
| `model` | `nano`/`flash`/`pro` | `pro` | `pro` 提供最佳的交叉质量。 |
| `ratio` / `size` | 字符串 | — | 可选；省略让模型决定。 |
### `generate_icon_set`
| 参数 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `prompts` | 字符串[] | — | **必填。** 每个图标一个提示。 |
| `output_dir` | 字符串 | — | **必填。** 文件按每个提示命名（`icon-shopping-cart.png`）。 |
| `model` | `nano`/`flash`/`pro` | `flash` | |
| `size` | `0.5K`/`1K`/`2K`/`4K` | `1K` | |
### `generate_from_video`
| 参数 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `youtube_url` | 字符串 | — | **必填。** 公开的YouTube网址。 |
| `prompt` | 字符串 | — | **必填。** 要从视频中生成的內容。 |
| `output` | 字符串 | — | **必填。** 输出文件路径。 |
| `ratio` | 字符串 | `16:9` | |
| `size` | `0.5K`/`1K`/`2K`/`4K` | `1K` | |
| `preview` | 布尔值 | `true` | |
## 提示
为了获得最佳结果，请写完整的句子描述 **主题 + 背景 + 光线 + 相机/镜头 + 情绪** - 叙事优于关键词汤。
> 一张老年日本陶艺家的照片级特写肖像，面部皱纹深刻，温暖微笑。柔和的黄金时段光线从窗户倾泻而入。 使用85mm人像镜头，背景虚化柔焦。宁静而高尚的气氛。
## 要求
- **Node.js 18+** （使用内置的 `node:test` 运行器和现代ES模块）
- **Gemini API密钥** (`GEMINI_API_KEY`)
- 交互式API处于 **测试阶段**；Gemini 3图像层级（`flash`、`pro`）可能需要访问。`nano`层级是最广泛可用的 - 如果您的密钥上`flash`/`pro`不可用，请设置 `model: "nano"`。
## 开发
```bash
npm test # 单元测试（node:test）- 不需要API密钥
npm run smoke # 实时烟雾测试 - 需要GEMINI_API_KEY
```
代码库分为专注的模块：
- `lib/config.js` - 模型表格、宽高比/尺寸验证、帮助程序
- `lib/gemini.js` - API客户端、重试、响应提取、预览
- `lib/tools.js` - 工具模式和处理程序
- `index.js` - MCP服务器线路
## 许可证
[MIT](LICENSE)
