内容
# @nanobanana/mcp 🍌
谷歌 **Nano Banana** （Gemini）图像模型的轻量级 [MCP](https://modelcontextprotocol.io) 服务器。它从任何MCP客户端（Claude Code、Claude Desktop、Cursor）生成和编辑图像，并返回 **文件路径而不是 base64**，因此代理的上下文保持较小。
- 三个工具，无其他功能：`generate_image`、`edit_image`、`list_models`
- 默认使用 Nano Banana 2（`gemini-3.1-flash-image`）。可在每次调用时或通过环境变量切换模型。如果固定的模型 ID 过时，`list_models` 将显示您的密钥实际可使用的模型。
- 多图像编辑：传递参考图像进行风格转换、角色或合成
- 控制长宽比（`1:1` 至 `21:9`）和分辨率（`1K`、`2K`、`4K`）
- 图像的谷歌搜索基础，提高现实世界准确性，如信息图表
- 安全的输出路径。服务器在桌面 MCP 客户端将其 spawn 到那里时，永远不会写入 `/`。
- 身份验证仅存在于环境变量中，因此您的 API 密钥永远不会通过聊天上下文传递
## 快速开始
在 [aistudio.google.com/apikey](https://aistudio.google.com/apikey) 获取免费的 Gemini API 密钥。
**Claude Code**
```bash
claude mcp add nanobanana -e GEMINI_API_KEY=your_key -- npx -y @nanobanana/mcp
```
也可在 [MCP Registry](https://registry.modelcontextprotocol.io) 中列为 `io.github.getjoystick/nanobanana-mcp`。
**Claude Desktop / Cursor**：将以下内容添加到 `claude_desktop_config.json` 或 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"nanobanana": {
"command": "npx",
"args": ["-y", "@nanobanana/mcp"],
"env": { "GEMINI_API_KEY": "your_key" }
}
}
}
```
## 工具
### `generate_image`
| 参数 | 必需 | 描述 |
|---|---|---|
| `prompt` | ✅ | 图像描述 |
| `model` | | Gemini 图像模型 ID（默认 `gemini-3.1-flash-image`） |
| `aspectRatio` | | `1:1`、`16:9`、`9:16`、`21:9`，极端情况下可达 `1:4` 和 `8:1` |
| `size` | | `512`、`1K`、`2K` 或 `4K` |
| `grounding` | | 使用谷歌搜索进行事实准确性验证 |
| `thinkingLevel` | | `minimal` 或 `high`；`high` 有助于复杂或文本密集型图像 |
| `outputDir` | | 保存目录（默认 `./nano-banana`） |
| `filename` | | 不带扩展名的基本文件名 |
### `edit_image`
相同参数，另外：
| 参数 | 必需 | 描述 |
|---|---|---|
| `images` | ✅ | 输入文件路径：png、jpg、webp、heic 或 pdf。第一个是基础；其余是参考。 |
两个工具都保存到磁盘并返回文件路径。
### `list_models`
不接受参数。列出您的 API 密钥可以使用的图像模型 ID。当固定的模型 ID 停止工作时很有用，这是早期 Nano Banana 服务器的故障方式。
## 配置
| 环境变量 | 描述 |
|---|---|
| `GEMINI_API_KEY` | **必需。** Gemini API 密钥（`GOOGLE_API_KEY` 也有效） |
| `NANOBANANA_MODEL` | 默认模型覆盖 |
| `NANOBANANA_OUTPUT_DIR` | 默认输出目录覆盖 |
## 模型
| 模型 ID | 备注 |
|---|---|
| `gemini-3.1-flash-image` | **默认。** Nano Banana 2：4K 输出，强大的文本渲染 |
| `gemini-3-pro-image` | Nano Banana Pro，用于需要更深入推理的复杂场景 |
| `gemini-2.5-flash-image` | 原始 Nano Banana（旧版；谷歌将于 2026-10-02 停止支持） |
## 开发
```bash
npm install
npm run build
GEMINI_API_KEY=your_key npm run smoke # 端到端测试，对抗实时 API
```
## 致谢
灵感来自其他 Nano Banana MCP。使用 [Claude Code](https://claude.com/claude-code) 构建。
## 许可证
MIT
