gen-image MCP server

gen-image MCP

中文 | English

面向 AI 编程 Agent 的本地图片工作流 MCP。通过用户自选的 OpenAI 兼容或 Gemini 图像接口生成、编辑图片，直接保存到项目目录。

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

为什么使用它

• 直接写入本地项目：生成或编辑的图片保存到调用 MCP 的机器，可立即被代码仓库引用。
• 使用自己的上游服务：自行配置 API 地址、Key 和模型，不依赖本服务托管模型。
• 失败自动恢复：可按配置顺序重试容量或限流错误，并切换到后续模型。
• 覆盖完整图片流程：支持文生图、本地参考图生成和图片编辑，并返回预览与资源链接。

使用前准备

• 安装 Node.js，建议使用 Node.js 24 LTS；服务最低要求为 20。
• 准备支持对应图像接口的服务地址、API Key 和模型名称。
• 使用支持 stdio 的 MCP 客户端。

本服务没有内置地址、Key 或模型。缺少必填配置会拒绝启动，也不会自动读取 .env 文件。

通过 npx 使用

包名：gen-image-mcp。

用户无需克隆源码、手动安装项目依赖或编译。npx 会自动下载并缓存 npm 包，再在本机启动服务；它不是远程托管服务。

在 MCP 客户端中添加一个 stdio 服务，启动命令与参数为：

命令：npx
参数：-y gen-image-mcp

下面是使用 mcpServers、command、args、env 字段的通用配置示例。不同客户端的配置结构可能不同，对应填入启动命令、参数和环境变量即可。

{
  "mcpServers": {
    "gen-image": {
      "command": "npx",
      "args": ["-y", "gen-image-mcp"],
      "env": {
        "GEN_IMAGE_BASE_URL": "https://your-proxy.example",
        "GEN_IMAGE_API_KEY": "your-api-key",
        "GEN_IMAGE_MODEL": "images-model-a,images-model-b",
        "GEN_IMAGE_GEMINI_MODEL": "gemini-image-model-a",
        "GEN_IMAGE_AUTO_FALLBACK": "true"
      }
    }
  }
}

将示例地址、Key 和模型替换为实际值。两组模型至少配置一组；不使用的组应删除对应环境变量，不要填写空字符串。图片读写发生在启动此 MCP 的机器上，建议使用绝对路径。

配置完成后，连接或重启该 MCP 服务，客户端应能发现四个工具。直接在终端启动时，服务会等待标准输入中的 MCP 消息，不会打开网页或交互式命令菜单。

生产使用建议将参数中的包名固定为已发布版本，例如 gen-image-mcp@，避免升级时行为变化。首次运行需要能够访问 npm 仓库。

命令行参数

也可以把非敏感配置放在启动参数中。以下命令要求已通过进程环境设置 GENIMAGEAPI_KEY：

npx -y gen-image-mcp --base-url "https://your-proxy.example" --model "images-model-a,images-model-b" --auto-fallback true

API Key 建议通过 MCP 客户端的环境变量配置传入，避免出现在命令历史和进程参数中。

配置项

命令行参数优先于环境变量。

模型名称不能重复，也不能包含空项。URL、Key 或配置值无效时直接报错，不会替换成默认服务或模型。

模型选择与失败切换

• 未指定工具参数 model 时，使用对应组的第一个模型。
• model 只能指定该组已经配置的模型。
• 开启自动切换后，上游 HTTP 错误、网络错误、超时或无有效图片会触发下一模型。
• 显式指定模型时，从该项开始，只向后尝试；不会绕回列表开头。
• 明确的容量不足或限流（含外层 500 包裹内层 503 / no capacity）会先对同一模型做有限退避重试（默认最多额外 2 次，并尊重有上界的 Retry-After）；超时、网络、鉴权、内容策略等错误不重试。
• 非上述可重试错误，或同模型重试仍失败后，才按开关切换下一模型；成功即停止，全部失败返回最后一个模型的结构化错误（保留 HTTP 状态与类别）。
• 每次调用重新从第一项或指定模型开始，不永久改变模型顺序。
• 单次调用参数 auto_fallback 可覆盖全局开关；设为 false 时只尝试当前模型（仍可对容量/限流做同模型重试）。
• 参数错误、本地图片读取错误和保存失败不触发模型切换。
• 两组模型不会跨接口切换。未配置某组时，其对应工具返回错误。

客户端的请求超时应为每个模型最多 3 次请求及两次退避等待留出余量；开启切换时还需乘以最多尝试的模型数，并考虑文件读写时间。无 Retry-After 时默认等待 400ms、800ms，单次等待最多 5 秒。普通 503 不视为明确容量不足。多次上游请求可能产生额外费用。

工具调用

以下 JSON 是工具参数，不是终端命令。三个生图/编辑工具都要求 prompt 和 outputpath；示例省略 model，使用对应组第一个模型。listmodels 无需参数。

generate_image

Shortened. The full README is on GitHub.