Codex / OpenAI Image

codex-openai-image-mcp

一个 MCP 服务，让 Claude（以及任何其他 MCP 客户端）能够 生成图像、编辑图像并制作风格一致的图像集，然后查看结果并继续操作。

它支持两种图像后端：

• Codex CLI：通过 Codex CLI 使用你已有的 ChatGPT 套餐。无需 API 密钥，也没有按图计费。
• OpenAI Images API：通过 OPENAI_API_KEY 使用，适合没有 Codex 的用户。

与 OpenAI 无关联，也未获其认可。“OpenAI”和“Codex”是 OpenAI 的商标。

编辑图像：“把它改成夜景，保留汽车和构图”

一次调用生成风格一致的图像集：“可爱的扁平风格贴纸：咖啡、仙人掌、月亮”

这两个示例都是由 Codex 后端生成的真实、未经修饰的输出。

与众不同之处

• 风格一致的图像集。 generate_set 可生成多张风格一致的不同图像，并分别以各自的名称保存。
• 两个后端，一个接口。 通过一个设置即可在 Codex 和 OpenAI API 之间切换。
• 专为 Agent 循环打造。 每次调用都会返回 Claude 可查看的小尺寸预览，在长时间运行时报告进度，可取消，并会在每张图像旁写入一个包含提示词和设置的 .json 附属文件。
• 谨慎处理你的文件。 只在输出文件夹中写入内容，从不覆盖现有文件，也不会更改你编辑的图像；Codex 则在空的临时文件夹中以只读模式运行。

快速开始

你需要 Node.js 20.3 或更高版本，以及以下其中一项：

• Codex CLI，已登录（codex login），并使用包含 Codex 图像生成功能的 ChatGPT 套餐；或
• 有额度的 OpenAI API 密钥。

Claude Code

# Codex backend (your ChatGPT plan)
claude mcp add images -e IMAGEGEN_PROVIDER=codex-cli -- npx -y codex-openai-image-mcp

# or the OpenAI API
claude mcp add images -e IMAGEGEN_PROVIDER=openai-api -e OPENAI_API_KEY=sk-... -- npx -y codex-openai-image-mcp

Claude Desktop、Cursor 和其他客户端

将以下内容添加到客户端的 MCP 配置中（Claude Desktop 使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "images": {
      "command": "npx",
      "args": ["-y", "codex-openai-image-mcp"],
      "env": { "IMAGEGEN_PROVIDER": "codex-cli" }
    }
  }
}

对于 API 后端，使用 "IMAGEGEN_PROVIDER": "openai-api"，并添加 "OPENAI_API_KEY"。

然后只需提出请求：

• “为我的博客页眉制作一只水彩风格的狐狸，尺寸为 1536x864。”
• “编辑 photo.png，让它看起来像日落时分。”
• “制作 5 个风格一致的应用图标：主页、搜索、个人资料、设置、铃铛。”

图像会保存在客户端启动目录下的 ./generated-images 中。

工具

generate_image

输入	默认值	说明
prompt	必填
size	1024x1024	任意 WxH 尺寸，每边为 16 到 4096 px
count	1	1–4 个变体，保存为 -v1、-v2、……
transparent	false	请求透明背景；如果输出没有透明背景，结果会说明
references	[]	最多 4 张用于匹配风格的图像
out_name	提示词的 slug	输出文件夹内的路径，不带扩展名，例如 icons/rocket

edit_image

输入	默认值	说明
image	必填	要修改的图像。原图绝不会被修改
prompt	必填	要进行的更改，例如“移除左侧的人”“改成水彩风格”
size	输入图像的尺寸	WxH
mask	无	PNG 图像，透明区域标示要编辑的位置（仅限 OpenAI API）
count	1	1–4 个变体
transparent	false	例如，用于抠图
references	[]	最多 3 张辅助图像：要插入的内容，或要应用的风格
out_name	<输入名称>-edited

generate_set

输入	默认值	说明
style	必填	所有图像共有的特征：媒介、调色板、渲染方式、背景
items	必填	1–8 个 { name, prompt }；每个图像都会保存为 <folder>/<name>.png
size	1024x1024	所有图像使用相同尺寸
transparent	false
references	[]	最多 4 张参考图，整套图像会匹配其风格
folder	style 的 slug	输出文件夹中的子文件夹

所有工具都会裁剪并调整结果尺寸，使其与指定尺寸完全一致，并返回保存路径 以及每张图像的 512 px 预览。

后端

	codex-cli	openai-api	mock
需要	Codex CLI，已登录	OPENAI_API_KEY	无
费用	你的 ChatGPT 计划用量	按图计费	免费
速度	每张约 30–60 秒	取决于模型和尺寸	即时
参考图、编辑、透明度	支持	支持	仅编辑
编辑遮罩	不支持	支持	不支持
套图	整套图像使用一个 Codex 会话	每次生成一张，第一张图像用作风格参考	每次一张

mock 会绘制占位图像，供你试用服务和运行测试。

Codex 后端。 每次调用都会运行 codex exec --json --skip-git-repo-check --sandbox read-only --cd <empty temp folder> [--image=<file>…] -- -， 并附上提示词，要求 Codex 只调用其内置的 image_gen 工具。服务 会从 Codex 的 JSON 事件中读取会话 ID，并从 $CODEX_HOME/generated_images/<session id>/ 收集图像。Codex 无法获得写入权限，也看不到你传入图像以外的项目内容。取消请求或达到超时后，Codex 都会停止。 请查看 OpenAI 关于使用计划以脚本方式调用 Codex CLI 的条款。

OpenAI 后端。 使用官方 openai SDK。默认模型为 gpt-image-2.5-sunburst；设置 IMAGEGEN_OPENAI_MODEL=gpt-image-2.5-flare 可获得更快的结果。尺寸 会先四舍五入到 API 接受的值，再调整为你指定的尺寸。此后端已通过针对模拟客户端的自动化测试；尚未进行完整的实测。

设置

变量	默认值
IMAGEGEN_PROVIDER	mock；设置为 codex-cli 或 openai-api
OPENAI_API_KEY	openai-api 必填
IMAGEGEN_OPENAI_MODEL	gpt-image-2.5-sunburst
IMAGEGEN_CODEX_BIN	codex
IMAGEGEN_OUT_DIR	generated-images，相对于工作文件夹
IMAGEGEN_READ_ROOT	工作文件夹；输入图像必须位于其中
IMAGEGEN_TIMEOUT_SEC	300，每张请求生成的图像
IMAGEGEN_MAX_PER_CALL	8 张图像
IMAGEGEN_PREVIEW_SIZE	512 px

文件与安全

• 输出仅写入 IMAGEGEN_OUT_DIR。绝对路径、.. 以及指向外部的符号链接都会被拒绝。
• 输入图像（用于编辑或作为参考图）必须位于 IMAGEGEN_READ_ROOT 中。
• 永远不会覆盖现有文件：新文件会改用 -2、-3……作为后缀。
• 每张图像都会附带一个 <name>.json 文件，其中记录提示词、后端、模型、尺寸、输入和时间。
• API 密钥仅从环境变量中读取，绝不会记录日志或写入附带文件。
• IMAGEGEN_MAX_PER_CALL 会限制单次调用可生成的图像数量。

图像由 AI 生成。你有责任妥善使用这些图像，包括遵守平台关于 AI 生成内容的规则，并避免模仿真实人物或品牌。

开发

git clone https://github.com/meet30997/codex-openai-image-mcp.git
cd codex-openai-image-mcp
npm install
npm run build
npm test          # unit and end-to-end tests; no network or API key needed
npm run inspect   # try the tools in the MCP Inspector

要从 Claude Code 运行本地构建：

claude mcp add images -e IMAGEGEN_PROVIDER=codex-cli -- node /path/to/codex-openai-image-mcp/dist/index.js

测试会使用替代脚本（test/fixtures/fake-codex.mjs）运行 Codex 后端，并使用模拟客户端运行 OpenAI 后端，因此免费且快速。PLAN.md 中包含设计说明和路线图。欢迎提交问题和拉取请求。

许可证

MIT