GPT Image 2 插件，适用于 Claude Desktop Code

通过本地打包的 MCP 服务器，使用 OpenAI GPT Image 2 生成和编辑项目图像。该插件每次付费调用生成一张经过验证的图像，将文件保存在已批准的项目工作区内，且从不覆盖已存在的目标路径。

简体中文

支持的 Claude 界面

本插件适用于 Claude Desktop Code，即 Claude Desktop 应用程序中面向项目的 Code 体验。不支持 Claude Desktop Chat。 它不是 MCPB 包，也不是远程 MCP 服务。

Related MCP server: mcp-openai-images-audio

通过 Claude Desktop Code 图形界面安装

GUI 插件安装是主要方式：

1. 在 Claude Desktop Code 中打开目标项目。

2. 打开 GUI 的 设置 → 插件 区域。标签可能因 Claude 版本略有不同。

3. 将此仓库根目录添加为本地市场，或选择其仓库源，然后安装 gpt-image-2@kpk-plugins。

4. 为当前项目启用已安装的插件。启用是项目特定的；安装插件不会自动授予对每个项目的访问权限。

5. 打开插件设置进行配置。不要将 .mcp.json 复制到普通设置中。

插件根目录就是市场根目录，市场入口指向 ./。

运行时要求

唯一的运行时依赖是 Node.js 20+，且必须在 Claude Desktop Code 可访问的 PATH 中。已安装的插件直接启动预构建的 dist/server.mjs。运行时，插件不运行 npm、npx、生命周期脚本、源代码编译，也不加载 node_modules。

已提交的市场副本包含独立包。安装副本测试仅启动 Git 跟踪的文件，并验证 get_status 在不存在 node_modules 目录且没有 API 密钥的情况下能否正常工作。

npm 和开发依赖项仅供构建或测试源代码检出项的贡献者使用。

在 GUI 中配置

在插件设置中，将 API 密钥输入到敏感的 OpenAI API key 字段中。不要将其放在命令行、.env、.mcp.json、普通设置、README、提示词或日志中，也不要让 Claude 显示或检查它。

默认的官方基础 URL 是：

https://api.openai.com/v1

自定义基础 URL 会接收本插件发送的 API 密钥、提示词和编辑图像。仅在你信任该端点及其操作者时才配置自定义 URL。自定义端点通常应包含 /v1；插件不会自动附加它。唯一面向用户的文档示例如下：

https://api.example.invalid/v1

URL 必须是绝对 HTTP(S) URL，不能包含凭据、查询、片段、控制字符或前后空白。兼容的端点必须实现 OpenAI 客户端使用的图像 API；仅凭接受 URL 并不意味着兼容。

对于受信任的本地或私有网络兼容端点，允许使用 HTTP，但会以无传输加密的方式发送 API 密钥、提示词和编辑图像。仅在你信任的网络和端点上使用 http:// 基础 URL；否则请优先使用 HTTPS。

安装后运行 /gpt-image-2:setup。该命令仅调用 get_status，不会发出任何提供者请求。

工具

get_status

仅报告安全的状态数据：是否配置了 API 密钥（布尔值）、是否配置了自定义基础 URL、运行中服务器的活动 URL 的 base_url_valid: true、已批准的工作区根目录、模型、服务器版本以及默认的相对输出目录。无效的已配置基础 URL 会阻止服务器启动；请在插件设置中更正它，然后重新加载或重启插件。get_status 不会发出任何提供者或图像 API 请求，并且永远不会返回密钥或基础 URL 值。

generate_image

使用模型 gpt-image-2 生成一张图像，固定 n: 1，并保存一个新文件。主要输入包括：

• prompt

• quality：auto、low、medium 或 high

• size

• output_format：png、jpeg 或 webp

• 可选的 JPEG/WebP output_compression，取值范围 0 到 100

• moderation：auto 或 low

• 可选的相对 output_path 和已批准的 workspace_root

edit_image

按提供的顺序编辑一到八个编辑输入，并保存一张新图像。输入可以是 PNG、JPEG 或 WebP。每个输入限制为 50 MiB，所有编辑图像加上可选的遮罩总计不超过 200 MiB。

可选的遮罩必须是带有 Alpha 通道的 PNG，与第一个输入图像的尺寸匹配，且小于 4 MiB。不支持透明输出背景；遮罩的 Alpha 仅用于标识编辑区域。

格式、尺寸和输出

• 输出格式：PNG、JPEG 和 WebP。

• 工具默认尺寸为 1024x1024。也接受 auto。

• 自定义的 WIDTHxHEIGHT 必须是 16 的倍数，每条边最多 3840 像素，宽高比必须在 1:3 到 3:1 之间，总像素数必须在 655,360 到 8,294,400 之间。

• PNG 不使用输出压缩。JPEG 和 WebP 接受 0 到 100 的压缩值。

• 如果省略 output_path，输出将放在 .claude/generated-images/gpt-image-2 下，文件名唯一且不包含提示词。

• 显式输出路径会保留，必须相对于已批准的工作区根目录，并且文件扩展名必须与请求的格式匹配。

• 拒绝已存在的目标路径。无覆盖发布机制还可防止并发调用替换同一目标。

实际尺寸在保存的图像解码并验证后保留并报告。如果显式请求的尺寸不同，文件仍以其实际尺寸保存，结果中会包含 SIZE_MISMATCH。

小于或等于 2 MiB 的图像包含内联预览。对于较大的图像，省略内联预览；保存的文件路径仍然是权威来源。TEMP_CLEANUP_PENDING 表示输出已成功保存，但临时发布文件的清理仍在进行中。

费用、并发和重试

生成和编辑是付费的提供者操作。该插件每次请求固定输出一张图像，并且每个服务器进程一次只允许一次付费调用。没有 SDK 重试机制，也没有应用程序重试机制，因此失败的付费调用不会自动重试。在调用图像工具之前，请确认提示词、编辑输入、尺寸、格式和输出路径。

工作区和安全边界

• 输出保留在 Claude Desktop Code 批准的工作区根目录内。输出路径不能是绝对路径，也不能遍历到根目录之外。

• 仅当包含的绝对输入路径已解析到已批准的根目录内时，才接受该路径；输入路径永远不会授予新的根目录。

• 输入文件通过稳定的句柄复制到私有临时快照中，然后上传。原始文件不会被修改。

• 提供者的输出经过严格解码、图像验证、刷新，并以无覆盖语义发布。

• 日志仅接受有界的状态码和数字上下文；提示词、API 密钥、基础 URL、图像数据、Base64 和完整输入路径均被排除。

Windows Node 20 下的符号链接边界

在 Windows 上使用 Node 20 时，会拒绝现有的重解析点/符号链接逃逸，并且在独占发布之前会立即重新检查输出父路径。由另一个相同权限的进程在检查之间主动替换目录，不在威胁边界内。要完全消除这种相同权限的替换竞争，需要使用本机 Win32 句柄相对辅助函数。

故障排除

• API 密钥未配置： 打开 Claude Desktop Code 插件设置，填写敏感的 API 密钥字段。不要将密钥粘贴到聊天或 shell 中。

• 自定义基础 URL 无效或未使用： 配置的无效基础 URL 会阻止服务器启动。在插件设置中更正它，确认设置已保存，然后重新加载或重启插件。自定义端点通常应以 /v1 结尾；不会自动添加 /v1 段。

• 没有已批准的工作区根目录： 在 Claude Desktop Code 中打开项目，并为该项目启用插件。

• OUTPUT_EXISTS： 选择一个新的相对输出路径。插件不会覆盖。

• SIZE_MISMATCH： 使用返回的实际宽度和高度；保存的图像是有效的。

• 预览被省略： 打开返回的相对或绝对路径；内联预览仅限于 2 MiB。

从源码构建和测试

开发命令可能会安装和使用开发依赖项；它们不属于已安装插件的运行时行为。验证命令会在检查批准的脚本集是否准确之前禁用隐式的 npm 生命周期钩子。

npm ci --ignore-scripts
npm run typecheck
npm test
npm run build
npm run test:dist
npm --ignore-scripts run validate

这些检查使用本地固定数据、模拟数据和协议测试。不需要付费的图像请求。未执行或声明任何实时提供者验证。

许可证

MIT © 2026 KPK。请参阅 LICENSE 和 THIRD_PARTY_NOTICES.md。