内容
# 纳米香蕉 MCP 服务器
用于通过 [Interactions API](https://ai.google.dev/gemini-api/docs/image-generation) 使用谷歌的 Gemini 图像模型生成和编辑图像的 MCP（模型上下文协议）服务器。两个工具都接受一个可选的 `model` 参数；默认是 `gemini-3.1-flash-image`（纳米香蕉 2）。
- [功能](#功能)
- [模型](#模型)
- [性能和成本](#性能和成本)
- [先决条件](#先决条件) · [安装](#安装) · [配置](#配置)
- [用法](#用法)
- [工具](#工具) — [`nanobanana_generate_image`](#nanobanana_generate_image) · [`nanobanana_edit_image`](#nanobanana_edit_image)
- [故障排除](#故障排除)
## 功能
- **可选模型**：在纳米香蕉 2、纳米香蕉 2 精简版和纳米香蕉 Pro 之间选择（参见下面的[模型表格](#模型)）
- **文本到图像生成**：从详细的文本提示创建图像
- **图像编辑**：使用自然语言指令修改现有图像
- **风格转换**：从参考图像应用艺术风格
- **多图像合成**：将多达 14 张图像组合成新的合成图像
- **高分辨率**：高达 4K 输出（取决于模型）
- **模型感知验证**：在任何 API 调用之前拒绝不支持的模型/分辨率或模型/长宽比组合 — 无静默降级
## 模型
使用两个工具中的可选 `model` 参数选择模型。默认是 `gemini-3.1-flash-image`。所有三个模型都只输出 **JPEG**，并共享相同的工具接口 — 能力差异在任何 API 调用之前都会被验证。
| 模型 ID | 名称 | 最适合 | 分辨率 | 极端长宽比 | 速度¹ | 每张图片成本² |
|----------|------|----------|-------------|-----------------------|--------|-------------|
| `gemini-3.1-flash-image`（默认） | 纳米香蕉 2 | 平衡的通用模型 | `0.5K`、`1K`、`2K`、`4K` | 是（`1:4`、`4:1`、`1:8`、`8:1`） | ~11 秒 | ~$0.07（1K） |
| `gemini-3.1-flash-lite-image` | 纳米香蕉 2 精简版 | 最便宜/最快 | 仅 `1K` | 否 | ~5 秒 | ~$0.034 |
| `gemini-3-pro-image` | 纳米香蕉 Pro | 最高质量 | `1K`、`2K`、`4K` | 否 | ~17 秒 | ~$0.13（1K） |
## 性能和成本
**速度**（¹）：通过此服务器测量的单个 **1K** 图像的近似时钟时间。延迟随分辨率（4K 明显较慢）而缩放，并随提示和 API 负载而变化。`num_images > 1` 运行多个 **独立** 请求，因此时间和成本线性缩放（例如 `num_images: 4` ≈ 4× 单个图像）。
**成本**（²）：编写时的大致每张图片价格（标准层）— **在 [Google 定价页面](https://ai.google.dev/gemini-api/docs/pricing) 上验证当前费率**，它们经常变化。更高分辨率的成本更高。标记为 _n/a_ 的单元格表示模型 **不支持** 该分辨率，因此在任何 API 调用之前请求被拒绝（没有这样的组合需要定价）：
| 分辨率 | 纳米香蕉 2 精简版 | 纳米香蕉 2（闪存） | 纳米香蕉 Pro |
|------------|--------------------|-----------------------|-----------------|
| `0.5K` | _n/a_ | ~$0.045 | _n/a_ |
| `1K` | ~$0.034 | ~$0.067 | ~$0.134 |
| `2K` | _n/a_ | ~$0.101 | ~$0.134 |
| `4K` | _n/a_ | ~$0.151 | ~$0.240 |
**经验法则：** 默认使用 **闪存** 进行日常工作；降低到 **精简版** 进行草稿、缩略图和高容量批次，其中速度和成本最为重要；选择 **Pro** 进行英雄镜头、照片逼真和电影灯光，其中额外的时间和成本是合理的。
## 先决条件
- 节点.js 18 或更高版本
- 谷歌 AI Studio API 密钥（[在这里获取](https://aistudio.google.com/)）
## 安装
```bash
# 克隆仓库
git clone https://github.com/spinje/nano-banana-mcp-server.git
cd nano-banana-mcp-server
# 安装依赖项
npm install
# 构建项目
npm run build
```
## 配置
将您的 API 密钥设置为环境变量：
```bash
export GEMINI_API_KEY="your-api-key-here"
# 或，为了兼容性
export GOOGLE_API_KEY="your-api-key-here"
```
## 用法
### 克劳德代码
将服务器添加到克劳德代码中作为本地 stdio MCP 服务器：
```bash
export GEMINI_API_KEY="your-api-key-here"
claude mcp add nano-banana \
--scope local \
--transport stdio \
--env GEMINI_API_KEY="$GEMINI_API_KEY" \
-- node /absolute/path/to/nano-banana-mcp-server/dist/index.js
claude mcp list
```
`--scope local` 将 MCP 服务器存储在您当前项目的私有克劳德代码配置中，而不是存储在此仓库中。启动克劳德代码后，运行 `/mcp` 以验证 `nano-banana` 是否已连接。
### 克劳德桌面版
添加到您的克劳德桌面版配置文件的 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```json
{
"mcpServers": {
"nano-banana": {
"command": "node",
"args": ["/absolute/path/to/nano-banana-mcp-server/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
```
### 直接运行
```bash
npm start
```
服务器通过 stdio 传输运行。当使用克劳德代码或克劳德桌面版时，您通常不需要自己运行此命令，因为 MCP 客户端会从其配置中启动服务器进程。对于本地开发、烟雾测试或将服务器连接到另一个 MCP 兼容客户端，此操作很有用。
## 工具
### nanobanana_generate_image
从文本提示生成图像。
**参数：**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `prompt` | 字符串 | 是 | - | 要生成的图像的文本描述 |
| `output_path` | 字符串 | 是 | - | 保存图像的文件路径（目录或完整路径）。任何扩展名都标准化为 `.jpg` |
| `model` | 字符串 | 否 | `"gemini-3.1-flash-image"` | 模型 ID：`gemini-3.1-flash-image`、`gemini-3.1-flash-lite-image`、`gemini-3-pro-image` |
| `aspect_ratio` | 字符串 | 否 | `"1:1"` | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`；另外 `1:4`、`4:1`、`1:8`、`8:1`（仅闪存）。如果所选模型不支持，则拒绝 |
| `resolution` | 字符串 | 否 | `"1K"` | `0.5K`、`1K`、`2K`、`4K`。如果所选模型不支持，则拒绝（精简版仅支持 `1K`；Pro 支持 `1K`/`2K`/`4K`） |
| `output_format` | 字符串 | 否 | `"jpeg"` | 仅支持 `jpeg`（这些模型输出 JPEG） |
| `num_images` | 数字 | 否 | `1` | 图片数量（1-4）。通过重复请求生成 |
| `temperature` | 数字 | 否 | `1.0` | 创造力（0.0-2.0） |
**示例：**
```
prompt: "日落时分风景如画的山湖，远处有雪峰"
output_path: ~/images/
prompt: "自信的女商人专业头像，工作室灯光"
output_path: ~/images/headshot.jpg
aspect_ratio: 3:4
```
### nanobanana_edit_image
使用文本指令编辑现有图像。
**参数：**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `prompt` | 字符串 | 是 | - | 编辑指令 |
| `image_paths` | 字符串[] | 是 | - | 图像路径或 URL 数组（1-14 张图像） |
| `output_path` | 字符串 | 是 | - | 保存结果的文件路径（目录或完整路径）。任何扩展名都标准化为 `.jpg` |
| `model` | 字符串 | 否 | `"gemini-3.1-flash-image"` | 模型 ID：`gemini-3.1-flash-image`、`gemini-3.1-flash-lite-image`、`gemini-3-pro-image` |
| `aspect_ratio` | 字符串 | 否 | `"auto"` | `auto`（保留原始）或任何生成比率。如果所选模型不支持，则拒绝 |
| `resolution` | 字符串 | 否 | `"1K"` | `0.5K`、`1K`、`2K`、`4K`。如果所选模型不支持，则拒绝（精简版仅支持 `1K`；Pro 支持 `1K`/`2K`/`4K`） |
| `output_format` | 字符串 | 否 | `"jpeg"` | 仅支持 `jpeg`（这些模型输出 JPEG） |
| `num_images` | 数字 | 否 | `1` | 变化数量（1-4）。通过重复请求生成 |
| `temperature` | 数字 | 否 | `1.0` | 创造力（0.0-2.0） |
**示例：**
```
prompt: "删除背景并替换为纯白色"
image_paths: ["~/photos/portrait.jpg"]
output_path: ~/edited/portrait-nobg.jpg
prompt: "将第二张图片的艺术风格应用于第一张图片"
image_paths: ["~/photos/landscape.jpg", "~/styles/vangogh.jpg"]
output_path: ~/edited/
prompt: "用逼真的颜色为这张黑白照片着色"
image_paths: ["~/old-photos/grandma-1950.jpg"]
output_path: ~/restored/
```
## 用例
### 基本生成
- 产品模型和可视化
- 社交媒体图形
- 概念艺术和插图
### 图像编辑
- 背景移除/替换
- 颜色校正和增强
- 对象添加/移除
### 风格转换
- 将艺术风格应用于照片
- 创建一致的视觉品牌
- 将图像转换为不同的艺术风格
### 多图像合成
- 将产品照片组合成目录
- 创建合成场景
- 在图像中保持角色一致性
## 开发
```bash
# 安装依赖项
npm install
# 构建
npm run build
# 自动重新加载的开发模式
npm run dev
# 清理构建工件
npm run clean
```
## 项目结构
```
.
├── src/
│ ├── index.ts # 入口点
│ ├── constants.ts # 配置常量
│ ├── types.ts # TypeScript 类型
│ ├── schemas/
│ │ ├── generate.ts # 生成工具模式
│ │ └── edit.ts # 编辑工具模式
│ ├── services/
│ │ ├── gemini-client.ts # Gemini API 客户端
│ │ └── file-utils.ts # 文件操作
│ └── tools/
│ ├── generate-image.ts # 生成工具
│ └── edit-image.ts # 编辑工具
├── dist/ # 编译输出（生成）
├── package.json
├── tsconfig.json
└── README.md
```
## 故障排除
### "未找到 API 密钥"
确保 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` 已设置在您的环境或 MCP 客户端配置中。
### "模型 … 不支持分辨率/长宽比 …"
请求的选项对于所选模型无效，并且在任何 API 调用之前请求被拒绝。检查[模型](#模型)表格 — 例如，精简版仅支持 `1K`，Pro 不支持极端长宽比，而只有闪存支持 `0.5K` 和 `1:4`/`4:1`/`1:8`/`8:1`。要么切换模型，要么选择支持的值。
### "内容被阻止"
提示可能触发了安全过滤器。尝试用较少明确或有争议的内容重新措辞。
### "速率限制超过"
您已经提出了太多请求。等待几分钟后再次尝试。
### "未找到图像文件"
验证图像路径是否正确。使用绝对路径或相对于主目录的路径（`~/`）。
### "图像超过 7MB 限制"
将输入图像调整为小于 7MB。
## 许可证
[MIT](LICENSE)
