MCP Nanobanana

🚀 纳米香蕉 - MCP图像生成扩展

纳米香蕉是一款专业的MCP（模型上下文协议）扩展，适用于任何支持MCP的客户端（包括Gemini CLI和Codex CLI），可用于生成和处理图像。它默认使用google/gemini-2.5-flash-image模型，并预先配置为连接到OpenRouter。你可以通过调整MODEL_*环境变量，将其指向任何托管该模型的提供商。

✨ 主要特性

• 🎨 文本到图像生成：根据描述性提示创建令人惊叹的图像。
• ✏️ 图像编辑：使用自然语言指令修改现有图像。
• 🔧 图像修复：恢复和增强老旧或受损的照片。
• 📁 智能文件管理：用户友好的文件名，自动防止重复。

📋 前提条件

1. 安装并配置支持MCP的CLI（例如Gemini CLI、Codex CLI）。
2. Node.js 18+ 和 npm。
3. API密钥：你需要从OpenRouter或其他托管google/gemini-2.5-flash-image模型的提供商处获取API密钥。

默认情况下，扩展会与OpenRouter进行通信。当你需要使用其他托管该模型的提供商时，可使用以下可选覆盖配置：

• MODEL_BASE_URL – 替代提供商的端点（默认值：https://openrouter.ai/api/v1）
• MODEL_ID – 覆盖模型ID（默认值：google/gemini-2.5-flash-image）
• MODEL_REFERER / MODEL_TITLE – 某些提供商需要的分析头信息
• MODEL_GENERATE_PATH – 替代生成端点路径（默认值：/responses）

如果你使用的是OpenRouter，请参考他们的身份验证指南来生成API密钥。对于其他提供商，请查阅他们的文档。

🚀 快速开始

📦 安装指南

从NPM安装（推荐）

对于大多数用户来说，通过npx或CLI的扩展管理器进行安装是最简单的方法。

Gemini CLI： 安装扩展时，系统会提示你输入API密钥。

gemini extensions install https://github.com/Aeven-AI/mcp-nanobanana

Codex CLI：

codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- npx -y @aeven/nanobanana-mcp@latest

Opencode CLI：

1. 运行opencode config edit（或手动打开opencode.jsonc设置文件）。
2. 使用类似以下的条目注册服务器：

{
    "mcp": {
        "nanobanana": {
            "type": "local",
            "command": ["npx", "-y", "@aeven/nanobanana-mcp@latest"],
            "enabled": true,
            "environment": {
                "MODEL_API_KEY": "{env:MODEL_API_KEY}"
            }
        }
    }
}

3. 保存文件并重启Opencode，使其加载新的MCP服务器。

Claude Code：

1. 打开Claude Code，导航到Settings → Model Context Protocol → Add Server。
2. 将命令设置为npx，参数设置为-y和@aeven/nanobanana-mcp@latest。
3. 添加一个环境变量MODEL_API_KEY，指向你的提供商密钥。
4. 保存服务器配置并重启Claude Code（或重新加载窗口）以进行连接。

本地开发安装

如果你已经克隆了这个仓库以进行代码开发，可以注册本地版本。 1. 安装服务器依赖（每次克隆后执行一次）：

npm run install-deps

2. 构建服务器：

npm run build

3. 在CLI中注册： Codex CLI：

codex mcp add nanobanana --env MODEL_API_KEY="YOUR_API_KEY_HERE" -- node mcp-server/dist/index.js

🔑 API密钥配置

此扩展需要MODEL_API_KEY才能与模型提供商（如OpenRouter）进行身份验证。以下是为不同客户端配置API密钥的方法：

Gemini CLI

安装过程中系统会自动提示你输入API密钥。

Codex CLI

codex mcp add命令有一个专门的--env标志来处理此问题。“安装”部分提供的命令已经包含了该标志，这是推荐的安装方式。

其他CLIs（Shell配置文件）

对于其他客户端，或者如果你更喜欢手动管理密钥，可以在shell的配置文件（例如~/.zshrc、~/.bashrc或~/.profile）中设置MODEL_API_KEY环境变量。

1. 在文件末尾添加以下行：

export MODEL_API_KEY="YOUR_API_KEY_HERE"

2. 重启终端使更改生效。

激活

重启你的MCP CLI（如Gemini CLI、Codex CLI等）。以下命令将可用：

• /generate - 单张或多张图像生成，支持风格/变体选项
• /edit - 图像编辑
• /restore - 图像修复
• /icon - 生成多种尺寸的应用图标、网站图标和UI元素
• /pattern - 生成用于背景的无缝图案和纹理
• /story - 生成讲述视觉故事或展示流程的系列图像
• /diagram - 生成专业的技术图表、流程图和架构模型
• /nanobanana - 自然语言接口

💻 使用示例

🎯 特定命令（推荐）

生成图像

# 单张图像
/generate "a watercolor painting of a fox in a snowy forest"

# 多张变体并预览
/generate "sunset over mountains" --count=3 --preview

编辑图像

/edit my_photo.png "add sunglasses to the person"
/edit portrait.jpg "change background to a beach scene" --preview

修复图像

/restore old_family_photo.jpg "remove scratches and improve clarity"

生成图标

/icon "coffee cup logo" --sizes="64,128,256" --type="app-icon" --preview

创建图案

/pattern "geometric triangles" --type="seamless" --style="geometric" --preview

生成故事图像

/story "a seed growing into a tree" --steps=4 --type="process" --preview

创建图表

/diagram "user login process" --type="flowchart" --style="professional" --preview

🌟 自然语言命令（灵活）

/nanobanana create a logo for my tech startup
/nanobanana I need 5 different versions of a cat illustration in various art styles
/nanobanana fix the lighting in sunset.jpg and make it more vibrant

🎨 高级生成选项

/generate命令支持高级选项，可用于创建具有不同风格和参数的多个变体。

高级示例

风格变体

/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# 以4种不同的艺术风格创建相同的山脉场景

多个变体

/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# 生成：戏剧性光照、柔和光照、欢快氛围、戏剧性氛围的版本

🎯 图标生成

/icon命令专门用于创建具有适当尺寸和格式的应用图标、网站图标和UI元素。

图标示例

# 完整的应用图标集
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# 网站图标包
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"

🎨 图案和纹理生成

/pattern命令用于创建适合作为背景和设计元素的无缝图案和纹理。

图案示例

# 网站背景图案
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# 材质纹理
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"

📖 视觉叙事

/story命令用于生成讲述视觉故事或展示逐步过程的系列图像。

故事示例

# 产品开发过程
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# 教育教程
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"

📊 技术图表

/diagram命令用于根据简单的文本描述生成专业的技术图表、流程图和架构模型。

图表类型和用例

• flowchart：流程、决策树、工作流
• architecture：系统架构、微服务、基础设施
• network：网络拓扑、服务器配置
• database：数据库模式、实体关系
• wireframe：UI/UX原型、页面布局
• mindmap：概念图、想法层次结构
• sequence：序列图、API交互

图表示例

# 开发工作流
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"

# 系统设计
/diagram "chat application architecture" --type="architecture" --style="technical"

📁 文件管理

智能文件名生成

图像会根据你的提示以用户友好的名称保存：

• "sunset over mountains" → sunset_over_mountains.png
• "abstract art piece" → abstract_art_piece.png

自动防止重复

如果文件已经存在，会自动添加计数器：

• sunset_over_mountains.png
• sunset_over_mountains_1.png
• sunset_over_mountains_2.png

文件搜索位置

在进行编辑/修复时，扩展会在以下位置搜索输入图像：

1. 当前工作目录
2. ./images/ 子目录
3. ./input/ 子目录
4. ./nanobanana-output/ 子目录
5. ~/Downloads/
6. ~/Desktop/

输出目录

生成的图像会自动保存到./nanobanana-output/目录。

🛠️ 开发

构建命令

# 构建MCP服务器
npm run build

# 安装MCP服务器依赖
npm run install-deps

# 开发模式，监听文件变化
npm run dev

MCP服务器命令

# 直接构建MCP服务器
cd mcp-server && npm run build

# 独立启动服务器（用于测试）
cd mcp-server && npm start

# 开发模式，监听TypeScript文件变化
cd mcp-server && npm run dev

测试

# 运行完整套件（构建 + 单元测试 + 集成测试）
cd mcp-server && npm test

# 仅运行单元测试（FileHandler、ImageGenerator使用模拟fetch）
cd mcp-server && npm run test:unit

# 仅运行集成测试（使用内存中的MCP握手和存根图像生成器）
cd mcp-server && npm run test:integration

默认的集成测试使用内存传输和存根图像生成器，因此可以离线运行，无需API密钥。

要端到端地测试真实的OpenRouter工作流，请在设置MODEL_API_KEY后运行手动脚本：

cd mcp-server
MODEL_API_KEY="sk-..." node ./tests/manual/openrouter.integration.js

生成的资产会放在mcp-server/nanobanana-output/目录下，以便手动检查。

验证npm打包

运行自动冒烟测试，确保发布的npm二进制文件能正确启动：

npm run verify:npm

此命令会打包项目，在临时目录中安装tarball，启动npx nanobanana-mcp，并确认stdio服务器横幅出现。在成功消息出现后可以安全中断。

🔧 技术细节

关键组件

• index.ts：使用@modelcontextprotocol/sdk的MCP服务器，用于专业的协议处理。
• imageGenerator.ts：处理所有OpenRouter API交互和响应处理。
• fileHandler.ts：管理文件I/O、智能文件名生成和文件搜索。
• types.ts：共享的TypeScript接口，确保类型安全。

MCP服务器协议

该扩展使用官方的模型上下文协议（MCP）SDK进行强大的客户端 - 服务器通信：

• 协议：通过stdio的JSON-RPC
• SDK：@modelcontextprotocol/sdk
• 工具：generate_image、edit_image、restore_image

API集成

• 模型：google/gemini-2.5-flash-image（可通过环境变量配置）
• 传输：直接HTTP请求（默认使用OpenRouter；设置MODEL_BASE_URL可指向其他托管该模型的提供商）
• 响应处理：Base64解码，对缺少的图像数据进行优雅降级处理
• 输出尺寸：所有图像均以1024×1024分辨率返回（模型最大分辨率）

错误处理

• 全面的错误消息，包含调试信息
• 对API响应解析进行优雅降级处理
• 文件验证和搜索路径报告

🐛 故障排除

常见问题

1. “命令未识别”：验证MCP服务器是否已为你的CLI注册（例如，Gemini CLI的~/.gemini/extensions/nanobanana-extension/，Codex用户的Codex CLI配置），并重启客户端。
2. “未找到API密钥”：确保在安装时提示输入API密钥时已正确输入，或者如果你不使用Gemini CLI，确保MODEL_API_KEY环境变量已正确设置。
3. “构建失败”：确保已安装Node.js 18+，并运行npm run install-deps && npm run build。
4. “未找到图像”：检查输入文件是否在上述搜索目录之一中。
5. npx安装错误：~/.npm/_npx中的陈旧目录可能导致安装失败。使用rm -rf ~/.npm/_npx/*删除缓存，然后重新运行安装命令。

调试模式

MCP服务器包含详细的调试日志，会显示在你的CLI控制台（如Gemini CLI、Codex CLI等）中，以帮助诊断问题。

📄 许可证

• 许可证：Apache License 2.0
• 安全：安全策略

🤝 贡献

1. 分叉仓库。
2. 创建功能分支。
3. 在模块化架构中进行更改。
4. 运行npm run build确保编译通过。
5. 使用你的MCP CLI（如Gemini CLI、Codex CLI等）进行测试。
6. 提交拉取请求。