Universal Image MCP for Codex

English｜简体中文

在Codex中通过你选择的官方或第三方API生成、编辑并显示图片。MCP在本地处理图片字节，只返回纯文本JSON、绝对文件路径和Markdown，主模型API无需接收图片工具内容块。

项目、npm包与命令名：universal-image-mcp；MCP与Skill名：universal-image。没有默认第三方地址或默认图片模型，必须明确配置连接。

新手上手示例

先确认Key属于生图分组。 很多第三方API平台需要在专门的生图分组下单独创建Key，分组常见名称为image、“生图”或“额外生图”。普通聊天、代码或其他模型分组的Key未必能直接生图。请先在供应商控制台确认该分组允许调用目标图片模型，再使用对应的Key；具体分组名称和权限规则以平台说明为准。

先按Windows安装完成配置，或把本项目地址发给Codex，让它协助完成安装步骤。配置完成后重启Codex，新建任务，描述你想生成的图片即可。下图展示了配置、自检和在对话中显示生成图片的流程：

Codex配置通用图片MCP、完成自检并生成图片的操作示例

截图中的Base URL与Key已遮挡。实际配置时，通过安装器的掩码提示输入Key；模型和图片尺寸以所选供应商的实际结果为准。

支持哪些API

协议	典型服务	文生图	参考图编辑
OpenAI Images	OpenAI官方、兼容此协议的第三方网关	支持	支持单张Multipart参考图
Gemini generateContent	Gemini原生接口及兼容网关	支持	支持inlineData参考图
OpenAI Chat图片输出	OpenRouter及兼容网关	支持	支持image_url参考图

支持自定义Base URL、模型、Bearer/请求头/无Key鉴权、路由、查询参数、额外请求头和扩展JSON。协议适配不等于任意供应商或模型都已实测；专用异步任务、ComfyUI工作流和OAuth服务需要专门适配。

供应商配置与示例
完整能力与降级表
授权在线测试记录
工程评估与后续方向

Windows安装

需要Windows10/11、可运行codex的Codex安装，以及图片服务账号或可信本地网关。不需要预装Node.js、npm或PowerShell 7，也不需要管理员权限。安装入口优先使用PowerShell7，未安装时兼容Windows内置PowerShell5.1。

从Releases下载Universal-Image-MCP-v2.0.0.zip并解压。
双击解压目录中的install.cmd，选择供应商并填写完整Base URL、图片模型ID和具有生图权限的Key；平台要求专用分组时，填写image或“生图”分组的Key。
等待安装完成，再完全关闭并重新打开Codex，新建任务。

Base URL包含供应商要求的版本前缀，例如https://your-provider.example/v1。不会自动添加/v1。OpenAI、Gemini和OpenRouter预设提供对应服务地址，仍需指定实际可用的图片模型。

PowerShell7中也可直接执行：

.\install.ps1 -Provider openai-compatible -BaseUrl "https://your-provider.example/v1" -Model "your-image-model"

Key通过掩码提示输入。完整JSON配置可用-ProviderConfigPath导入；环境变量引用会转发变量名到Codex，不把变量值复制到Codex配置。无Key本地网关使用auth_type: "none"。

安装器下载并校验官方Node.js24.19.0便携运行时，离线安装包内依赖，保护状态目录权限，注册MCP与Skill，并将MCP工具超时设为600秒后反读验证。默认安装在D:\CodexTools\universal-image-mcp；没有D盘则使用%LOCALAPPDATA%\CodexTools\universal-image-mcp。不修改系统PATH。

Get-FileHash -LiteralPath .\Universal-Image-MCP-v2.0.0.zip -Algorithm SHA256
Get-Content -LiteralPath .\Universal-Image-MCP-v2.0.0.zip.sha256

在Codex中使用

使用$universal-image生成一张图片：白色背景上的红色纸鹤，居中构图，柔和阴影，不要文字。生成后把图片显示在对话中。

编辑时给出本地图片绝对路径和具体修改要求。当前参考图限单张PNG/JPEG/WebP、最大10MB；不支持mask或多参考图。

工具	用途	可能计费
`image_doctor`	检查配置、鉴权和可选模型目录	否
`list_image_models`	查询当前连接的模型目录	否
`explain_image_capability`	解释模型选择和参数限制，不作未验证能力保证	否
`generate_image`	生成并保存图片	是
`edit_image`	提交参考图编辑并保存图片	是
`inspect_image`	检查本地文件格式、尺寸和哈希	否

Doctor的generation_channel_status=not_probed表示没有提交生图请求。模型目录暂时不可用不会单独证明生图渠道不可用；已有明确模型且鉴权未被拒绝时仍可执行用户授权的一次调用。

model=auto使用配置模型，或目录中唯一可识别的图片候选。多个候选时不会猜测。显式模型不会被不完整目录拦截。通用工具不默认发送质量、格式、背景等可选参数；支持范围由实际协议和模型决定。

所有生图和编辑请求均只提交一次；不因503、429、超时或网络中断自动重试、换模型或换供应商。返回的实际像素、格式和数量与请求不一致时会标记degraded并保留结果。

升级与迁移

v2.0.0是破坏性更新：包、入口文件、安装目录、状态目录、MCP和Skill都使用通用名称。v1.x的专属环境变量、隐式地址、历史选型策略与能力快照不再使用。

从v1.x迁移时，先保存必要配置，再用旧版安装器卸载旧实例，随后安装v2.0.0并显式选择供应商。不要把旧配置文件中的Key直接与新地址拼接；请按新格式导入完整连接。历史版本保留在Git标签和旧Release中。

v2.x更新时重新运行新版安装器，无参数更新保留完整配置。-Model修改模型；-ResetApiKey更新Key；切换地址或供应商时清除旧连接的鉴权与路由。

.\install.ps1 -Uninstall

卸载仅移除可验证归属的当前安装、MCP注册和Skill链接，不删除生成图片。

源码与多供应商

Node.js22或更高版本运行npm ci后，参考Codex手动配置。macOS/Linux可运行Node源码；自动安装器目前面向Windows。多个MCP实例可用不同配置文件和Key，并在任务中指定目标实例。

常见问题

base_url_required：配置完整Base URL，或选择一个明确的供应商预设。
model_required：填写供应商控制台或模型目录返回的实际图片模型ID。
Key能聊天但不能生图：检查Key是否属于image、“生图”或“额外生图”分组，以及该分组是否开放目标图片模型。需要时在正确分组下新建Key，再用-ResetApiKey更新配置；仅修改模型名称不会增加Key权限。
invalid_api_key：确认Key与当前站点匹配，并具有图片服务权限。
missing_header_env：确保启动Codex的环境能访问所引用变量，仅在其他终端中设置不会传给已有桌面进程。
MCP error -32001: Request timed out：这是宿主超时，检查600秒配置并重启Codex。上一请求计费状态未知，不要自动重试。
实际尺寸/格式不符：查看data.result.deviations；MCP不会偷偷转码、裁切或提交第二次请求。
图片URL为内网地址：结果下载仍拒绝私网、回环和不安全跳转。可让本地网关直接返回Base64。

开发验证

npm ci
npm test
npm audit --omit=dev --audit-level=moderate
.\scripts\build-release.ps1

离线测试不访问图片供应商。scripts/live-mcp-smoke.mjs会提交真实计费请求，仅在Key所有者授权后使用。测试与密钥文件不能进入提交。

本项目是独立社区集成，采用MIT License，不是任何API供应商或Codex的官方项目。

Universal Image MCP for Codex