Image Gen MCP

English

Image Gen MCP 是一个品牌中立、可自托管的图片生成与编辑 MCP server，同时提供 Codex plugin 与 image-gen Skill。Agent 可以直接用自然语言生成图片、编辑本地参考图，或按顺序组合多张参考图；结果会保存到本地，并同时以 MCP 图片内容和结构化元数据返回。

为什么使用

• 一个稳定工具：Agent 始终调用 generate_image，底层 provider 可配置切换。
• 生成与编辑统一：支持纯文本生成、单参考图和最多 12 张有序参考图。
• 本地结果可追踪：返回绝对路径、真实 MIME、格式、大小、provider、model、request ID 与 revised prompt（若上游提供）。
• 默认安全：凭据不进入工具参数；校验参考图魔数与大小；输出防路径穿越且默认不覆盖；URL 结果默认仅允许公网 HTTPS。
• 标准 MCP：使用官方 SDK，可由支持 stdio MCP 的客户端调用，不局限于某个 Agent 产品。

让 Agent 使用

配置好环境变量并启用 MCP server 后，可以直接说：

• “生成一张夜间列车穿过雪原的电影海报，保存为 night-train.png。”
• “编辑 /path/to/photo.jpg：保留人物与构图，把背景改成雨天街道。”
• “依次参考这三张图：第一张控制构图，第二张控制色彩，第三张控制材质。”

Skill 会调用 mcp__image_gen__generate_image。也可由任意 MCP 客户端直接调用 generate_image，传入 prompt，并按需使用 reference_image、reference_images、provider、model、size、quality、output_format、output_directory、filename、overwrite 与 action。

两种协议

openai-images（默认）

遵循标准 OpenAI-compatible Images API：无参考图时向 /images/generations 发送 JSON；有参考图时向 /images/edits 发送 multipart。解析标准 b64_json，也支持经过安全下载策略校验的 url 结果。适合直接提供 Images API 的服务。

openai-responses

向 /responses 发起非流式请求，把提示词和参考图 data URL 放入输入内容，并启用 image_generation tool。只解析最终输出中明确的 image_generation_call.result。action 可设为 auto、generate 或 edit。这里的 model 是 Responses 主控制模型，不一定等于 Images API 的图片模型，可用 IMAGE_GEN_RESPONSES_MODEL 单独设置。

最小配置

export IMAGE_GEN_API_KEY="your-key"
export IMAGE_GEN_MODEL="your-model"
npm start

常用配置包括 IMAGE_GEN_PROVIDER、IMAGE_GEN_BASE_URL、IMAGE_GEN_RESPONSES_MODEL、IMAGE_GEN_OUTPUT_DIR 与 IMAGE_GEN_TIMEOUT_MS。OPENAI_API_KEY、OPENAI_BASE_URL 是低优先级兼容别名。也可以用 IMAGE_GEN_ENV_FILE 指向严格的 KEY=value 文件；该文件不会作为 shell 脚本执行。完整占位示例见 .env.example。

默认输出目录是 ~/Pictures/Image Gen。已有同名文件不会被覆盖，除非工具调用显式传入 overwrite: true。

兼容性边界

“OpenAI-compatible”仅表示本项目实现这里描述的标准 Images 或 Responses 请求/响应形状。它不保证任意图片厂商只填写 API key 就能兼容；字段、模型能力、参考图数量和输出格式仍由所配置服务决定。不兼容的协议应通过新的 provider adapter 接入，而不是伪装成现有协议。

当前版本一次调用固定请求并返回一张最终图片，不处理流式 partial image。自动重试仅适用于网络错误、HTTP 429 和 5xx；400、401、403 不重试。

隐私与网络

参考图片及提示词会发送给你配置的外部 provider。 请先确认服务方的数据政策，并不要发送未经授权的敏感图片。API key 不在 MCP 工具 schema 中，但仍应由客户端安全管理环境变量。

上游返回图片 URL 时，默认要求公网 HTTPS，并阻断 loopback、link-local 与私网地址，同时限制重定向、下载大小和超时。只有连接可信的内部兼容服务时才应显式设置 IMAGE_GEN_ALLOW_PRIVATE_URLS=true。

故障排查

• CONFIG_ERROR：检查 API key、model、base URL 与严格 env 文件格式。
• INVALID_IMAGE：确认参考图是普通 PNG/JPEG/WebP 文件，扩展名与内容一致且未超限。
• FILE_EXISTS：换用文件名，或明确允许覆盖。
• AUTH_ERROR / RATE_LIMITED / UPSTREAM_ERROR：检查 provider 凭据、配额和服务状态。
• UNSAFE_URL：上游 URL 未满足默认公网 HTTPS 策略。

开发与安全说明见 CONTRIBUTING.md 和 SECURITY.md。