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

用于任何MCP兼容客户端（包括Gemini CLI和Codex CLI）的专业MCP（模型上下文协议）扩展，用于生成和操作图像。它使用 google/geni-2.5-flash-image 默认情况下，该模型已预先配置为连接到OpenRouter。您可以通过调整 MODEL_* 环境变量。

✨ 特性

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

📋 先决条件

MCP兼容CLI 已安装和配置（例如，Gemini CLI、Codex CLI）
Node.js 18+ 和npm
API密钥：您将需要来自OpenRouter或其他承载的提供程序的API密钥 google/gemini-2.5-flash-image 模型。

默认情况下，扩展与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命令行界面：

跑 opencode config edit （或打开你的 opencode.jsonc 手动设置文件）。

使用类似于以下内容的条目注册服务器：

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

保存文件并重新启动Opencode，以便它能够启动新的MCP服务器。

克劳德代码：

打开Claude Code并导航到 设置→ 模型上下文协议→ 添加服务器.
将命令设置为 npx 以及关于 -y 和 @aeven/nanobanana-mcp@latest.
添加环境变量 MODEL_API_KEY 指向您的提供者密钥。
保存服务器配置并重新启动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）进行身份验证。以下是如何为不同的客户端配置它：

Gemini CLI

在安装过程中，系统将提示您自动输入API密钥。

Codex CLI

这 codex mcp add 命令有一个专用 --env 旗帜为你处理这件事。“安装”部分中提供的命令已经包含了这一点，并且是推荐的安装方式。

其他CLIs（壳牌简介）

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

在文件末尾添加以下行：

   export MODEL_API_KEY="YOUR_API_KEY_HERE"

重新启动终端以使更改生效。

激活

重新启动MCP CLI（Gemini CLI、Codex CLI等）。以下命令将可用：

/generate -具有样式/变化选项的单张或多张图像生成
/edit -图像编辑
/restore -图像恢复
/icon -生成多种大小的应用图标、收藏夹图标和UI元素
/pattern -为背景生成无缝的图案和纹理
/story -生成讲述视觉故事或过程的连续图像
/diagram -生成技术图、流程图和架构模型
/nanobanana -自然语言界面

💡 用法

该扩展为不同的用例提供了多种命令选项：

注：以下示例使用Gemini CLI斜线命令。在Codex CLI和其他MCP客户端中，调用相同的MCP工具(generate_image, edit_image等等）使用客户端提供的语法。

🎯 特定命令（推荐）

生成图像：

# Single image
/generate "a watercolor painting of a fox in a snowy forest"

# Multiple variations with preview
/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 命令支持高级选项，用于创建具有不同样式和参数的多个变体。

\ \生成选项\

--count=N -变体数量（1-8，默认值：1） --styles="style1,style2" -逗号分隔的艺术风格 --variations="var1,var2" -具体变异类型 --format=grid|separate -输出格式（默认：单独） --seed=123 -可重复变异的种子 --preview -在默认查看器中自动打开生成的图像

\ \可用样式\

photorealistic -摄影质量图像
watercolor -水彩画风格
oil-painting -油画技法
sketch -手绘草图风格
pixel-art -复古像素艺术风格
anime -动漫/漫画艺术风格
vintage -复古/复古美学
modern -现代/现代风格
abstract -抽象艺术风格
minimalist -干净、简约的设计

\ \可用变体\

lighting -不同的照明条件（戏剧性、柔和）
angle -各种视角（上图，特写）
color-palette -不同的配色方案（暖色、冷色）
composition -不同的布局（居中，三分法）
mood -各种情绪基调（欢快、戏剧性）
season -不同季节（春季、冬季）
time-of-day -不同时间（日出、日落）

高级示例

风格变化：

/generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
# Creates the same mountain scene in 4 different artistic styles

多种变体：

/generate "cozy coffee shop" --variations="lighting,mood" --count=4
# Generates: dramatic lighting, soft lighting, cheerful mood, dramatic mood versions

🎯 图标生成

这 /icon 该命令专门用于创建具有适当大小和格式的应用程序图标、favicons和UI元素。

\ \图标选项\

图标示例

# Complete app icon set
/icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"

# Website favicon package
/icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"

🎨 图案和纹理生成

这 /pattern 命令创建无缝的图案和纹理，非常适合背景和设计元素。

\ \图案选项\

模式示例

# Website background pattern
/pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"

# Material texture
/pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"

📖 视觉叙事

这 /story 命令生成连续的图像，讲述一个视觉故事或演示一个循序渐进的过程。

\ \故事选项\

故事示例

# Product development process
/story "idea to launched product" --steps=5 --type="process" --style="consistent"

# Educational tutorial
/story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"

📊 技术图表

这 /diagram 命令从简单的文本描述生成专业技术图、流程图和架构模型。

\ \图表选项\

图表类型和用例

流程图：流程、决策树、工作流
建筑：系统架构、微服务、基础设施
网络：网络拓扑、服务器配置
数据库：数据库架构、实体关系
线框：UI/UX模型、页面布局
思维导图：概念图、想法层次结构
序列：序列图，API交互

图表示例

# Development workflow
/diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"

# System design
/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

文件搜索位置

对于编辑/恢复，扩展程序在以下位置搜索输入图像：

当前工作目录
./images/ 子目录
./input/ 子目录
./nanobanana-output/ 子目录
~/Downloads/
~/Desktop/

输出目录

生成的图像保存到 ./nanobanana-output/ 它是自动创建的。

🛠️ 发展

构建命令

# Build the MCP server
npm run build

# Install MCP server dependencies
npm run install-deps

# Development mode with file watching
npm run dev

MCP服务器命令

# Build MCP server directly
cd mcp-server && npm run build

# Start server standalone (for testing)
cd mcp-server && npm start

# Development mode with TypeScript watching
cd mcp-server && npm run dev

测试

# Run the full suite (build + unit + integration)
cd mcp-server && npm test

# Only unit tests (FileHandler, ImageGenerator with mocked fetch)
cd mcp-server && npm run test:unit

# Only integration tests (in-memory MCP handshake with a stub image generator)
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：MCP服务器使用 @modelcontextprotocol/sdk 用于专业协议处理
imageGenerator.ts：处理所有OpenRouter API交互和响应处理
fileHandler.ts：管理文件I/O、智能文件名生成和文件搜索
types.ts：用于类型安全的共享TypeScript接口

MCP服务器协议

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

协议：基于标准输入的JSON-RPC
软件开发工具包: @modelcontextprotocol/sdk
工具: generate_image, edit_image, restore_image

API集成

模型: google/gemini-2.5-flash-image （可通过环境变量配置）
运输：直接HTTP请求（默认情况下为OpenRouter；设置 MODEL_BASE_URL 针对托管该模型的其他提供商）
响应处理：Base64解码，对丢失的图像数据进行优雅的回退
输出大小：所有图像均以1024×1024分辨率（型号最大值）返回

错误处理

包含调试信息的全面错误消息
API响应解析的优雅后退
文件验证和搜索路径报告

🐛 故障排除

常见问题

“无法识别命令”：验证MCP服务器是否已为您的CLI注册（例如。， ~/.gemini/extensions/nanobanana-extension/ 对于Gemini CLI，Codex用户的Codex CLI配置）并重新启动客户端

“找不到API密钥”：确保在安装过程中出现提示时正确输入了API密钥，或者 MODEL_API_KEY 如果您没有使用Gemini CLI，则环境变量设置正确。

“构建失败”：确保Node.js 18+已安装并运行 npm run install-deps && npm run build.

“找不到图像”：检查输入文件是否位于搜索到的目录之一中（请参阅上面的文件搜索位置）

npx 安装错误：中的旧目录 ~/.npm/_npx 可能导致安装失败。使用以下命令删除缓存 rm -rf ~/.npm/_npx/* 并重新运行安装命令。

调试模式

MCP服务器包括出现在CLI控制台（Gemini CLI、Codex CLI等）中的详细调试日志记录，以帮助诊断问题。

📄 法律

许可证：Apache许可证2.0
安全: 安全策略

🤝 贡献

分叉存储库
创建要素分支
在模块化架构中进行更改
跑 npm run build 确保汇编
使用您的MCP CLI（Gemini CLI、Codex CLI等）进行测试
提交拉取请求

MCP Nanobanana

快速接入

详细介绍