gpt-image-mcp

基于 TypeScript 的本地 stdio MCP 服务，调用 GPT Image 完成文生图、图片编辑和参考风格创作，图片保存在本机，返回绝对路径及文件 URI。

安装与配置

需要 Node.js 22 或更高版本，以及具有所选模型调用权限和可用额度的 OpenAI 或兼容服务商 API 密钥。支持 Linux、macOS 和 Windows。无需手动安装，通过 npx 自动下载运行。

MCP 配置（适用于 Claude Code、Claude Desktop、Cursor 等支持 MCP 的客户端）：

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "你的 API 密钥",
        "OPENAI_BASE_URL": "https://你的服务商/v1",
        "IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
        "IMAGE_GEN_OUTPUT_DIR": "~/pictures"
      }
    }
  }
}

仅 OPENAI_API_KEY 必填，其余按需配置。详见下方配置章节。

首次启动会自动下载依赖，之后使用缓存。工具执行超时建议设为至少 360 秒；服务自身的 API 超时默认为 300 秒。

配置

环境变量	默认值	说明
`OPENAI_API_KEY`	必填	OpenAI API 密钥，通过客户端环境变量注入
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	未填写或留空时使用官方端点；仅填写域名时自动补 `/v1`，已有路径保留
`IMAGE_GEN_MODEL`	`gpt-image-2.5-sunburst`	文生图和编辑共用的模型，允许兼容服务商的模型别名，需账号有权限
`IMAGE_GEN_OUTPUT_DIR`	用户主目录下的 `gpt-image-mcp/images`	输出根目录，支持本机绝对路径或 `~/`；自动按本地日期创建 `yyyy/MM/dd` 子目录
`IMAGE_GEN_TIMEOUT_MS`	`300000`	API 请求超时，单位毫秒，必须为不小于 1000 的整数
`IMAGE_GEN_RESPONSE_FORMAT`	`b64_json`	API 返回图片的方式：`b64_json`（返回 Base64 数据）或 `url`（返回下载地址，服务自动下载保存）。默认 `b64_json` 时不向 API 发送此参数，仅配置 `url` 时才显式发送。部分代理对新模型（如 `gpt-image-2.5-sunburst`）可能不支持此参数，遇到 `unknown_parameter` 错误时请保持默认值
`IMAGE_GEN_DEFAULT_SIZE`	`auto`	全局默认分辨率，格式为 `WIDTHxHEIGHT`（如 `1024x1024`）。不填或留空时使用 `auto`，由 API 自行决定。宽高需为 16 的倍数，比例不超过 3:1，总像素 655360~8294400。单次调用仍可通过 `size` 参数覆盖
`IMAGE_GEN_DEFAULT_QUALITY`	`auto`	全局默认质量：`auto`、`low`、`medium`、`high`、`xhigh`、`max`。不填或留空时使用 `auto`，由 API 自行决定。单次调用仍可通过 `quality` 参数覆盖

OPENAI_BASE_URL 填写 API 根地址；未配置、空字符串或纯空格均使用官方端点。只有地址不包含路径时自动补 /v1，已有路径则按用户配置保留，避免破坏代理前缀或其他版本。尾部斜杠会去除，不会重复追加 /v1。

用户填写	实际使用的 API 根地址
不填	`https://api.openai.com/v1`
`https://gateway.example`	`https://gateway.example/v1`
`https://gateway.example/`	`https://gateway.example/v1`
`https://gateway.example/v1/`	`https://gateway.example/v1`
`https://gateway.example/proxy/v1/`	`https://gateway.example/proxy/v1`
`https://gateway.example/proxy/`	`https://gateway.example/proxy`

服务在根地址后追加 /images/generations、/images/edits 或 /models，不要填写完整生图接口地址。自定义路径如果需要 /v1，请明确填成 /proxy/v1。支持 HTTP 和 HTTPS，本地代理可用 http://localhost:8080；远程端点建议使用 HTTPS。地址不能包含账号密码、查询参数或 URL 片段。

Key、提示词和输入图片会发送到你配置的服务商。服务不会跟随 HTTP 重定向，请直接填写最终 API 根地址。

兼容服务商必须支持 OpenAI Image API 的 JSON 文生图、multipart 图片编辑，以及 data[].b64_json 或 data[].url 返回结构。服务会自动识别两种返回格式并正确处理。部分代理对新模型不支持 response_format 参数，保持 IMAGE_GEN_RESPONSE_FORMAT 默认值即可正常使用。仅兼容聊天接口或异步任务 ID 的服务不在当前兼容范围内。

端点检查与实际能力验证

服务启动时只校验本地配置，不自动联网探测或生成测试图片。需要检查时，在 MCP 客户端调用 check_endpoint，参数为 {}；也可以在配置好环境变量后运行：

gpt-image-mcp --check

诊断最多等待 30 秒，不自动重试，只请求 GET /models，不会调用图片生成或编辑接口。结果说明：

字段	含义
`configuration`	`valid` 表示本地配置格式合法，不代表密钥已获授权
`modelsEndpoint`	`available` 表示模型列表响应结构正确；`unavailable` 表示请求失败；`unexpected_response` 表示返回内容不符合列表结构
`modelListed`	当前模型是否出现在本次返回的列表中，无法确定时为 `null`
`generation` / `editing`	本项检查始终返回 `unverified`，不会将模型列表成功当成图片能力证明
`httpStatus` / `message`	HTTP 状态码和说明，不回显密钥或上游原始错误消息

有些图片服务不提供 /models，或不会列出别名模型，所以检查失败和模型未列出都不会禁止生图。CLI 在模型列表正常时退出码为 0，其余情况为 1；退出码不代表图片能力通过或失败。

真正的兼容性验证需要分别执行一次 generate_image 和 edit_image，检查图片返回和落盘是否成功。这些调用可能计费，建议先使用 quality: "low"。文生图通过不能替代编辑接口测试，也不能保证所有参数组合均被服务商支持。

文件命名与路径

图片按 输出根目录/yyyy/MM/dd/文件名 保存，年月日取自实际保存时用户电脑的本地时间，月份和日期补齐两位，不采用 UTC 日期。跨天保存自动进入新目录。

文件名使用自建俏皮词表，组合“形容词 + 小动物 + 动作 + 奇妙事物 + 随机短码”，不额外调用语言模型取名：

cozy-otter-paints-moonlight-7d3a9b2c.png
sassy-capybara-juggles-marshmallows-c8e2a104.webp
dreamy-axolotl-brews-stardust-f0914abc.jpg

默认路径示例：

Linux:   /home/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png
macOS:   /Users/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png
Windows: C:\Users\用户名\gpt-image-mcp\images\2026\09\10\cozy-otter-paints-moonlight-7d3a9b2c.png

输出根目录保持固定，按日期归档；图片文件名使用 ASCII 小写字母、连字符和随机短码，避免系统保留字符与大小写差异。每次使用独占方式创建文件，名称碰撞会重新取名，绝不覆盖已有图片。支持中文和空格目录；uri 使用标准 URL 编码。旧版本生成的图片保留原位，不会自动迁移。

结果中的 path 是本机路径，uri 是 file:// URI，均不是公网下载地址。调用客户端必须能访问服务所在机器的文件系统；是否内联显示图片取决于客户端。图生图可以直接使用上一次返回的 path。

工具

`generate_image`

{
  "prompt": "一只水獭在月光下画画，暖色手绘插画，柔和笔触",
  "size": "1024x1024",
  "quality": "medium",
  "format": "png"
}

`edit_image`

{
  "prompt": "保留图一主体和构图，参考图二的配色与笔触，将背景改为雨夜街道",
  "images": ["/绝对路径/原图.png", "/绝对路径/风格参考.webp"],
  "quality": "high"
}

局部编辑可增加 mask，填写本机遮罩路径。遮罩必须是含透明通道的 PNG，尺寸与第一张原图一致；完全透明区域表示希望编辑的部分。遮罩是模型的编辑指引，不保证像素级边界精确。

参数	默认值与范围
`prompt`	必填，去除首尾空白后 1～32000 字符
`size`	默认 `auto`，也可选 `WIDTHxHEIGHT`（如 `1024x1024`、`1536x1024`、`3840x2160`）。宽高需为 16 的倍数，比例不超过 3:1，总像素 655360～8294400
`quality`	默认 `auto`，也可选 `low`、`medium`、`high`、`xhigh`、`max`
`format`	默认 `png`，也可选 `jpeg`、`webp`
`background`	默认 `auto`，也可选 `transparent`、`opaque`；透明背景需配合 `png` 或 `webp` 格式
`moderation`	仅文生图，默认 `auto`，也可选 `low`；内容安全审核级别
`output_compression`	可选 0～100 整数，仅 `jpeg` 和 `webp` 格式生效
`input_fidelity`	仅编辑，可选 `high` 或 `low`；控制对原图细节的保留程度
`images`	编辑必填，1～16 张本机 PNG、JPEG 或 WebP；单图小于 50 MiB，参考图合计不超过 100 MiB
`mask`	编辑可选，本机 PNG 遮罩路径；单文件小于 50 MiB

输入图片路径必须为本机绝对路径或以 ~/ 开头。每次生成一张新图片，不修改输入文件。

成功时同时返回 MCP 文本和 structuredContent，内容一致：

{
  "images": [{
    "path": "/Users/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png",
    "uri": "file:///Users/%E7%94%A8%E6%88%B7%E5%90%8D/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png",
    "mimeType": "image/png",
    "bytes": 123456,
    "width": 1024,
    "height": 1024
  }],
  "model": "gpt-image-2.5-sunburst"
}

失败返回 isError: true 和错误说明。服务关闭自动重试；超时或断线不代表上游没有执行，重新调用可能再次计费。图片生成成功但本地保存失败时会明确提示，不会重新调用生成接口。客户端取消会传递给 API 请求，但无法保证取消上游已开始的计费。

真实验收建议用 quality: "low" 各执行一次文生图和图生图，确认账号模型权限、网络、图片效果与客户端展示行为。