gen-image MCP

gen-image MCP

中文 | English

[npm version] [MCP Registry] [License: MIT]

GitHub 项目：yuluo688/gen-image-mcp | 已登记 官方 MCP Registry

在 Claude Code、Cursor、VS Code 里一句话调用 GPT Image 或 Gemini（Nano Banana）生图、改图，图片直接存进项目目录；模型挂了自动切换到下一个。

[gen-image MCP 演示：在 Claude Code 中一句话生成图片并保存到项目]

为什么用它

• 图片直接落到项目里：保存在运行 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

claude mcp add --env GEN_IMAGE_BASE_URL=https://your-gateway.example \  --env GEN_IMAGE_API_KEY=your-api-key \  --env GEN_IMAGE_MODEL=gpt-image-2,gpt-image-1.5 \  --env GEN_IMAGE_GEMINI_MODEL=gemini-3.1-flash-image,gemini-2.5-flash-image \  --env GEN_IMAGE_AUTO_FALLBACK=true \  --transport stdio gen-image -- npx -y gen-image-mcp

加 --scope user 可在所有项目中使用。注意最后一个 --env 和服务名之间要隔一个其他参数（如 --transport stdio）。

• Cursor：[一键添加到 Cursor]，安装后在 ~/.cursor/mcp.json 里把占位地址和 Key 换成真实值。
• VS Code：[在 VS Code 中安装]（会弹窗让你输入地址和 Key）。

Claude Desktop / Cline / Windsurf 等使用 mcpServers 的客户端

{  "mcpServers": {    "gen-image": {      "command": "npx",      "args": ["-y", "gen-image-mcp"],      "env": {        "GEN_IMAGE_BASE_URL": "https://your-gateway.example",        "GEN_IMAGE_API_KEY": "your-api-key",        "GEN_IMAGE_MODEL": "gpt-image-2,gpt-image-1.5",        "GEN_IMAGE_GEMINI_MODEL": "gemini-3.1-flash-image,gemini-2.5-flash-image",        "GEN_IMAGE_AUTO_FALLBACK": "true"      }    }  }}

OpenCode（项目里的 opencode.json 或全局 ~/.config/opencode/opencode.json；Windows 上改为 "command": ["cmd", "/c", "npx", "-y", "gen-image-mcp"]）

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "gen-image": {      "type": "local",      "command": ["npx", "-y", "gen-image-mcp"],      "enabled": true,      "environment": {        "GEN_IMAGE_BASE_URL": "https://your-gateway.example",        "GEN_IMAGE_API_KEY": "your-api-key",        "GEN_IMAGE_MODEL": "gpt-image-2,gpt-image-1.5",        "GEN_IMAGE_GEMINI_MODEL": "gemini-3.1-flash-image,gemini-2.5-flash-image",        "GEN_IMAGE_AUTO_FALLBACK": "true"      }    }  }}

各客户端字段名不同：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。”

工具一览

详细文档

配置说明 · 模型选择、失败切换与重试 · 工具参数参考 · 文件、输出与 structuredContent · 常见问题 · 参与开发

许可证：MIT © 2026 yuluo688。不替代上游模型服务条款，也不约定生成图片的权利归属。