用途
gen-image-mcp 是一个本地运行的 MCP（Model Context Protocol）服务器，目标是在 Claude Code、Cursor、VS Code 等支持 MCP 的客户端里，用一句话完成图片生成与编辑，并让生成的图片直接落到项目目录中，方便代码立即引用。项目已登记官方 MCP Registry。
主要能力
- 图片直接落到项目里：图片保存在运行 MCP 的机器上，代码马上就能引用。
- 使用自己的服务和 Key：支持任意 OpenAI 兼容的 Images 接口（如 gpt-image-2、gpt-image-1.5 等），或经 OpenAI 兼容网关提供的 Gemini 图像模型（Nano Banana 系列）。本项目不托管任何模型。
- 失败自动切换：容量不足、限流时先做有限退避重试，再按顺序换到下一个模型。
- 生图、参考图、改图全覆盖：支持文生图、参考图生成、多图编辑和蒙版，返回内联预览和 structuredContent。
使用方式
环境要求为 Node.js ≥ 20（推荐 24 LTS）。需要准备：服务根地址（不带 /v1，服务会自动拼接 /v1/images/* 和 /v1/chat/completions）、API Key，以及至少一组模型。资料中的模型名只是示例，需填写服务商实际提供的模型 ID；不用的那组应删除对应变量，不要留空字符串。
在配置中加 --scope user 可在所有项目中使用。注意最后一个 --env 和服务名之间要隔一个其他参数（如 --transport stdio）。
- Cursor：安装后在
~/.cursor/mcp.json里把占位地址和 Key 换成真实值。 - VS Code：安装后会弹窗让输入地址和 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。”
适用场景
适合在 IDE / 编码助手环境中需要快速产出配图、头图、素材并直接写入项目目录的开发者，以及希望使用自有 API 服务和 Key、对模型供应商有自主控制权的用户。
限制
- 依赖用户自备的 OpenAI 兼容接口或 Gemini 图像模型服务与 API Key，项目不提供模型托管。
- 需要 Node.js ≥ 20（推荐 24 LTS）。
- 模型名需填写服务商实际提供的 ID，示例名称不保证可用。
- 许可证为 MIT，不替代上游模型服务条款，也不约定生成图片的权利归属。
