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@<version>，避免升级时行为变化。首次运行需要能够访问 npm 仓库。

命令行参数

也可以把非敏感配置放在启动参数中。以下命令要求已通过进程环境设置 GEN_IMAGE_API_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 和 output_path；示例省略 model，使用对应组第一个模型。list_models 无需参数。

generate_image

{
  "prompt": "白色桌面上的红色立方体，柔和自然光",
  "output_path": "exports/cube.png",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "output_format": "png",
  "auto_fallback": true
}

可选参数：filename、model、size、quality、n、output_format、auto_fallback。size 默认 auto；n 为 1–4，默认 1；quality 可取 low、medium、high、auto；output_format 可取 png、jpeg、webp，省略时由上游决定。

edit_image

{
  "prompt": "将天空改为日落，保留建筑细节",
  "output_path": "exports/edited.png",
  "images": ["inputs/photo.png"],
  "auto_fallback": true
}

images 必填，包含 1–16 个本地图片路径。可选参数：filename、mask（本地蒙版路径）、model、size、quality、auto_fallback。蒙版和编辑能力取决于上游模型。

generate_gemini_image

{
  "prompt": "将这张草图转为水彩画",
  "output_path": "exports/watercolor.png",
  "images": ["inputs/sketch.png"],
  "aspect_ratio": "16:9",
  "auto_fallback": false
}

省略 images 即为纯文生图。可选参数：filename、images、model、aspect_ratio、auto_fallback。

支持的宽高比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9。

list_models

调用参数为 {}。返回文本和 structuredContent，包含按配置顺序排列的 groups：每组有 api（images 或 gemini）、models、default_model 和 tools。未配置的组返回空列表及 default_model: null；顶层 auto_fallback 表示全局切换设置。

此工具只读取本地配置，不发网络请求、不返回 API Key 或服务地址。availability_checked: false 明确表示没有检查模型当前是否可用。

AI 文件命名

由调用方 AI 根据主题填写可选 filename，服务本身不额外调用模型命名。三个生图/编辑工具均支持：

{
  "prompt": "夕阳花园中的优雅成年女性人像，自然光摄影",
  "output_path": "exports/",
  "filename": "夕阳花园人像.png",
  "n": 1
}

filename 是单个文件名，不是路径，可包含中文，扩展名可省略，最终后缀以实际图片格式为准。名称最多 200 个 UTF-8 字节，为序号和后缀预留空间。提供该参数时 output_path 必须为目录；空名称、路径分隔符、Windows 保留名称等无效输入会在生图请求前拒绝。

同名输出通过独占创建和递增序号防覆盖，例如 夕阳花园人像.png、夕阳花园人像-2.png、夕阳花园人像-3.png，最多尝试 1000 个候选名称。多图输出先添加图片序号，再处理已有文件冲突。不传 filename 时保持原有命名方式。

文件与输出

• 输入和输出的相对路径均相对于 MCP 进程工作目录，而不是 npm 缓存或包安装目录；不确定工作目录时使用绝对路径。
• output_path 以 / 或 \ 结尾、指向现有目录，或没有受支持的图片扩展名时，按目录处理。
• 未指定 filename 时，目录输出命名为 {slug}-{YYYYMMDD-HHmmss}-{随机UUID}[-序号].扩展名；纯中文提示词的 slug 为 image，时间戳使用本地时间。
• 文件输出保留指定基名；多张图片插入 -1、-2 等序号，扩展名以实际图片格式为准。
• 缺少的父目录会自动创建。直接将 output_path 设为文件时仍覆盖，不备份；目录输出采用独占创建，不覆盖已有文件。使用 filename 时自动尝试序号后缀，其他目录输出遇到碰撞则报错。
• 最多输入 16 张图片，每个本地输入文件最多 50 MiB。
• 图片响应只接受可识别的 PNG、JPEG、WebP、GIF Base64 或 data URL，不会自动下载上游返回的普通远程 URL。

返回内容

成功时依次返回：

1. 保存路径和 gen-image:///<id> 资源 URI 的文本。
2. 第一张图片的内联预览，仅在其解码大小不超过 2 MiB 时附带。
3. 每张图片的 resource_link。

三个生图/编辑工具还返回 structuredContent，便于客户端直接处理，不必解析文本路径：

执行失败时保留 isError: true 和错误文本，并返回上述摘要、空 images 及 error。SDK 输入 schema 校验失败发生在执行前，不保证附带执行摘要。摘要不额外记录提示词、密钥或完整请求/响应正文，也不新增历史数据库。

客户端可以通过 resources/list 列出当前服务实例保存的图片，再用 resources/read 读取完整 Base64 内容；资源读取不受 2 MiB 预览限制。服务重启后资源列表清空，但已经保存的文件不会删除。

工具失败返回 isError: true 和错误文本。stdout 仅用于 MCP 协议，日志写入 stderr。

常见问题

npx 提示找不到包

检查包名、版本和 npm 仓库地址。可运行 npm view gen-image-mcp version --registry=https://registry.npmjs.org 查询公共仓库中的版本；第三方镜像可能存在同步延迟。

提示配置缺失或没有可用模型

检查 MCP 进程是否收到 URL、Key 和至少一组模型环境变量。只配置 Gemini 模型时，请使用 generate_gemini_image；只配置 Images 模型时，请使用 generate_image 或 edit_image。

命令启动后没有页面或输出

这是 stdio MCP 服务，不提供 HTTP 服务或网页。有效配置下，它需要由 MCP 客户端连接并发送协议消息。

找不到生成的图片

以工具返回的绝对保存路径为准。使用 npx 不会把图片自动保存到 npm 包目录；可以直接指定绝对 output_path。

开源许可证

本项目采用 MIT 许可证，版权归属 Copyright (c) 2026 yuluo688。

允许商用、修改和分发，包括闭源使用；须保留版权及许可证声明。软件按原样提供，不作担保。该许可证适用于本项目软件，不替代上游模型服务条款或对生成图片权利的约定。