gen-image MCP

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

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/mcp.json 里把占位地址和 Key 换成真实值。
• 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。”

工具一览

工具	用途	上游端点
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 · 常见问题 · 参与开发

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