Codex Images

codex-images-mcp

通过任意 MCP 客户端生成和编辑图像，使用你已付费的 ChatGPT 方案中的 gpt-image-2。无需 OpenAI API 密钥，也无需按图付费。

codex-images-mcp 是一个用于 Codex Images 端点的 MCP 服务。它可在本地通过 stdio 运行，也可作为可自托管的 HTTP 服务运行，供你的笔记本电脑、VPS 上的 Agent，以及 Pi / Gentle Shell 会话共享。每张生成的图像都会附带可验证的工件信息：SHA-256、字节数、MIME 类型和实际尺寸。

非官方。 与 OpenAI 无关，也未得到 OpenAI 的认可。它使用你自己的 ChatGPT 账号登录，并使用与 Codex CLI 相同的端点。你必须遵守 OpenAI 对你账号的使用条款，图像生成会计入方案限额。

你将获得

• 两个工具：codex_images（生成 / 编辑）和 codex_images_artifact（通过 URI 获取图像，可内嵌返回，也可通过短时有效的签名下载链接获取）。
• 批量处理：parallel、variants、chain 和 branded-parallel（每张图像都会引用同一个锚点，以生成品牌风格一致的图像集）。
• 带参考图和蒙版的编辑：每个请求最多可提供五张参考图，支持 HTTPS URL 或内嵌图像。
• 原生透明背景：模型可生成真正带 alpha 通道的 PNG；如果结果为不透明图像，则会发出警告。
• 精确输出尺寸：支持 native、exact、fit 或 cover 后处理，因此 1200×630 的卡片最终尺寸就是 1200×630。
• 提示词原样发送：中间不会有隐藏的改写模型。
• 可选的 API 密钥引擎：设置 CODEX_IMAGES_ENGINE=api 并提供 OPENAI_API_KEY，即可自行选择模型（Images 2.6 gpt-image-2.6-sunburst / -flare），质量最高可设为 max，并可控制复杂度。此引擎的费用计入你的 API 账号。默认的 ChatGPT 方案路径由 OpenAI 选择模型，API 选择器（model、quality、complexity）会被忽略。
• 默认安全的自托管：内置 bearer 身份验证；没有令牌时拒绝公开监听；获取 URL 时会强化 SSRF 防护（仅限 HTTPS 和公共地址、固定 IP、不跟随重定向）；结果中不包含服务器路径。
• 独立的 ChatGPT 会话：codex-images-mcp login 使用设备代码登录并保留独立会话，因此不会轮换（也不会破坏）Codex 应用的登录状态。

快速开始（本地，stdio）

uvx --from codex-images-mcp codex-images-mcp login     # sign in once (device code)
uvx --from codex-images-mcp codex-images-mcp setup     # register in Claude Code, Claude Desktop, Codex, Cursor, OpenCode

也可以在终端中试用：

uvx --from codex-images-mcp codex-images-mcp generate "a ceramic mug, studio light" --transparent --pretty

已经登录 Codex CLI？codex-images-mcp 可在令牌过期前以只读方式使用该登录状态。它不会刷新令牌；如需使用独立会话，请运行 login。

输出示例

以下是通过此服务使用 gpt-image-2 生成的示例。为适应此页面，图片已缩小。使用透明背景生成图像，以及发送参考图和蒙版进行编辑的示例，详见 docs/examples.md。

左侧的图像使用提示词 a ceramic mug, studio light 生成，并设置了 transparent。模型返回了一个 1536×1024 的 PNG，大小为 1,745,462 字节，sha256 为 e0d0338218529ca36e0d64e92eb2737c6794b392343f1a5ab32884a49dab48ba。编辑时，将该杯子作为参考图，并在正面覆盖蒙版，然后要求添加一个深棕色的小咖啡豆印章。返回的 PNG 尺寸为 1536×1024，sha256 为 7c5b28d4950f5207c111f875ef9d19349e06be3da43ce1200d2d8d2c678b9ba5。相机角度略有变化。蒙版只是提示，模型可能会调整整个画面。

生成结果是带有真实 alpha 通道的 PNG。棋盘格只是背景，因此可以看到透明背景：

此文件夹中还包含：米白色背景的生成图、棋盘格背景上的编辑图，以及 1200px 的透明 PNG：生成图和编辑图。

自托管（HTTP）

export CODEX_IMAGES_HTTP_TOKEN=$(openssl rand -hex 32)
docker compose up -d
docker compose run --rm codex-images codex-images-mcp login

然后将客户端指向 https://your-host/mcp/，并使用 Authorization: Bearer $CODEX_IMAGES_HTTP_TOKEN。反向代理、签名下载和所有设置请参阅 docs/self-hosting.md。

Pi 和 Gentle Shell

pi-codex-images 是面向自托管服务的 Pi 扩展。它会读取你授权的本地文件，将其内联发送，并以原子方式将经过验证的结果写入你的项目：

pi install npm:pi-codex-images

文档

• MCP 工具参考：输入、结果和错误代码。
• 命令行：generate、login、logout、setup、status、uninstall。
• 自托管：Docker、反向代理、配置和安全模型。
• 示例：批量处理、编辑、蒙版、透明度和精确尺寸。
• 比较：与类似项目的区别。

致谢

codex-images-mcp 最初是 wauwa 创建的 VelmoAI/codex-imagen 的分支。安装程序和许多原始结构均源自该项目。OAuth 令牌处理基于 Small Turtle 2 创建的 codex-image-gen。生成引擎已替换为原生 Codex Images 端点，并移除了提示词重写和色度键图层。

许可证

MIT。请参阅 LICENSE 和 NOTICE。