yuluo688/gen-image-mcp

中文 | English
GitHub 项目：yuluo688/gen-image-mcp | 已登记 官方 MCP Registry
**在 Claude Code、Cursor、VS Code 里一句话调用 GPT Image 或 Gemini（Nano Banana）生图、改图，图片直接存进项目目录；模型挂了自动切换到下一个。**
为什么用它
- **图片直接落到项目里**：保存在运行 MCP 的机器上，代码马上就能引用。
- **用自己的服务和 Key**：任意 OpenAI 兼容的 Images 接口（gpt-image-2、gpt-image-1.5 等），或经 OpenAI 兼容网关提供的 Gemini 图像模型（Nano Banana 系列）。本项目不托管任何模型。
- **失败自动切换**：容量不足、限流先有限退避重试，再按顺序换下一个模型。
- **生图、参考图、改图全覆盖**：文生图、参考图生成、多图编辑和蒙版，返回内联预览和 structuredContent。
30 秒上手
需要 Node.js ≥ 20（推荐 24 LTS）。准备好 **服务根地址**（不带 /v1，服务会自动拼接 /v1/images/* 和 /v1/chat/completions）、**API Key**，以及至少一组模型。下面的模型名只是示例，请填写你的服务商实际提供的模型 ID；不用的那组请删掉对应变量，不要留空字符串。
**Claude Code**
加 --scope user 可在所有项目中使用。注意最后一个 --env 和服务名之间要隔一个其他参数（如 --transport stdio）。
- **Cursor**： ，安装后在 ~/.cursor/mcp.json 里把占位地址和 Key 换成真实值。
- **VS Code**： %22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gen_image_api_key%22%2C%22description%22%3A%22Image%20API%20key%22%2C%22password%22%3Atrue%7D%5D%7D)（会弹窗让你输入地址和 Key）。
**Claude Desktop / Cline / Windsurf 等使用 mcpServers 的客户端**
**OpenCode**（项目里的 opencode.json 或全局 ~/.config/opencode/opencode.json；Windows 上改为 "command": ["cmd", "/c", "npx", "-y", "gen-image-mcp"]）
> **各客户端字段名不同**：env 还是 environment，command + args 还是单个 command 数组，mcpServers 还是 mcp / servers，请按你的客户端文档的格式填写。**Windows 原生环境**：如果服务起不来（Connection closed、ENOENT），请通过 cmd 启动 npx，例如 "command": "cmd", "args": ["/c", "npx", "-y", "gen-image-mcp"]。
重启客户端，应能看到 4 个工具。然后直接说：*“生成一张 16:9 的落地页头图，保存到 public/hero.png。”*
工具一览
| 工具 | 用途 | 上游端点 |
| --- | --- | --- |
| generate_image | 文生图（尺寸、质量、1–4 张、png/jpeg/webp） | POST /v1/images/generations |
| edit_image | 编辑或合并 1–16 张本地图片，可加蒙版 | POST /v1/images/edits |
| generate_gemini_image | Gemini 文生图或参考图生成，支持 10 种宽高比 | POST /v1/chat/completions |
| list_models | 查看已配置的模型组和默认模型（不联网） | 无 |
详细文档
配置说明 · 模型选择、失败切换与重试 · 工具参数参考 · 文件、输出与 structuredContent · 常见问题 · 参与开发