Skip to main content
Glama

gpt-image-mcp

GPT Image 图像生成与编辑的 MCP Server,为 LLM 客户端提供标准化的工具调用能力。

NPM Version CI Status License

特性

  • Images + Responses 双接口:支持 /v1/images/generations、/v1/images/edits 与 Responses API 的 image_generation 工具。

  • GPT Image 2 / 2.5:默认使用 gpt-image-2.5-flare 生成、gpt-image-2.5-sunburst 编辑,兼容 gpt-image-2 及日期快照。

  • 自定义 endpoint:通过 GPT_IMAGE_BASE_URL 接入 OpenAI 兼容中转站,自动补 /v1。

  • 两端鉴权:入站 HTTP 支持 Authorization: Bearer / X-API-Key;出站自动注入上游 API Key。

  • 内联 + 落盘:默认返回 MCP image content;Node 下可传 output_path 写入本地文件。

  • 三种运行方式:stdio、Streamable HTTP、Cloudflare Workers,共用同一套工具代码。

  • 统一结果约定:成功返回 Markdown + structuredContent(+ 可选 image content),失败走 isError 通道。

Related MCP server: Taskade MCP Server

目录

快速开始

必须配置上游 API Key。以下示例同时适用于 OpenAI 官方端点与中转站:

export GPT_IMAGE_API_KEY=sk-...
# 可选:中转站地址,服务会自动补 /v1
export GPT_IMAGE_BASE_URL=https://relay.example.com

直接运行(stdio,默认传输方式):

npx -y -p @aemeath-projects/gpt-image-mcp gpt-image-mcp

在 Claude Code 中注册:

claude mcp add gpt-image \
  -e GPT_IMAGE_API_KEY=sk-... \
  -e GPT_IMAGE_BASE_URL=https://api.openai.com \
  -- npx -y -p @aemeath-projects/gpt-image-mcp gpt-image-mcp

Claude Desktop 配置示例:

{
  "mcpServers": {
    "gpt-image": {
      "command": "npx",
      "args": ["-y", "-p", "@aemeath-projects/gpt-image-mcp", "gpt-image-mcp"],
      "env": {
        "GPT_IMAGE_API_KEY": "sk-...",
        "GPT_IMAGE_BASE_URL": "https://api.openai.com"
      }
    }
  }
}

本地 mock 或无需鉴权的中转站可显式设置 GPT_IMAGE_API_KEY="",此时不会发送 Authorization 头。Windows 下若客户端找不到 npx,可将 command 改为 cmd, 并在 args 开头加入 /c。

工具

所有工具都声明 annotations。成功时返回 Markdown 文本与 structuredContent; 默认还会附带 MCP image content。失败时返回 isError: true 与单行中文错误信息。

工具

用途

generate_image

通过 Images API 生成图片

edit_image

通过 Images API 编辑图片,支持多图与 mask

generate_image_via_responses

通过 Responses API 生成/编辑图片

generate_image

参数

类型/默认

说明

prompt

string,1–32000,必填

提示词

model

string,默认 GPT_IMAGE_MODEL

必须以 gpt-image- 开头

n

integer 1–10,默认 1

生成数量

size

string,默认 auto

auto 或 宽x高,按模型能力校验

quality

low/medium/high/xhigh/max/auto,默认 medium

xhigh/max 仅 2.5 系列支持

background

transparent/opaque/auto,默认 auto

transparent 只能配 png/webp

output_format

png/jpeg/webp,默认 png

输出格式

output_compression

integer 0–100,可选

仅 jpeg/webp

moderation

auto/low,默认 auto

内容审核级别

output_path

string,可选

Node 下落盘路径

overwrite

boolean,默认 false

是否覆盖已存在文件

inline

boolean,默认 true

为 false 时必须提供 output_path

edit_image

在 generate_image 参数基础上增加:

参数

类型/默认

说明

images

string[],1–16,必填

支持 http(s)://、data:、本地路径(本地路径仅 Node)

mask

string,可选

局部重绘遮罩,来源同 images

input_fidelity

low/high,可选

仅 gpt-image-1.5 / gpt-image-1-mini 支持,2 / 2.5 会显式报错

单图使用 multipart 字段 image,多图默认使用 image[]。中转站不兼容时可通过 GPT_IMAGE_MULTI_IMAGE_FIELD 改为 image。

generate_image_via_responses

参数

类型/默认

说明

prompt

string,1–32000,必填

提示词

images

string[],0–16,可选

作为 input_image 传入

model

string,默认 GPT_IMAGE_MODEL

image_generation 工具的图像模型

text_model

string,默认 gpt-6-astra

Responses 顶层文本模型

size / quality / background

同上

传给 image_generation 工具

action

auto/generate/edit,默认 auto

工具动作

effort

minimal/low/medium/high,默认 high

文本模型推理强度,映射到 reasoning.effort

previous_response_id

string,可选

多轮编辑

output_path / overwrite / inline

同上

落盘与内联控制

成功结果的 structuredContent 包含 model、images[](mimeType、bytes、 可选 path / revisedPrompt)、saved_paths、usage 等字段;Responses 工具额外返回 response_id。

落盘命名

  • output_path 以 / 或 \ 结尾,或指向已存在目录:image_1.png、image_2.png……

  • n > 1 且指向文件:stem-1.png、stem-2.png……

  • 未提供扩展名时按 output_format 补全。

  • 默认不覆盖;存在同名文件时整体失败。内联返回模式下会保留图片并给出 warning, inline: false 时直接报错。

运行方式

stdio

pnpm build
GPT_IMAGE_API_KEY=sk-... pnpm start    # 等价于 node dist/cli.js

从 npm 运行:

GPT_IMAGE_API_KEY=sk-... npx -y -p @aemeath-projects/gpt-image-mcp gpt-image-mcp

Streamable HTTP

MCP_API_KEY=local-dev GPT_IMAGE_API_KEY=sk-... pnpm start:http

默认监听 http://127.0.0.1:3000/mcp。健康检查固定为 GET /health,不受 --path 影响且不鉴权。配置 MCP_API_KEY 后,/mcp 需要携带 Authorization: Bearer <key> 或 X-API-Key: <key>。

# 健康检查(公开)
curl -s http://127.0.0.1:3000/health

# 列出工具(需要鉴权)
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Authorization: Bearer local-dev' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 生成图片
curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Authorization: Bearer local-dev' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_image","arguments":{"prompt":"a red ceramic cube","size":"1024x1024","quality":"low"}}}'

响应为 SSE,result.content 同时包含 Markdown 与 image content, result.structuredContent 是不含 base64 的元数据。

Node 侧默认绑定 127.0.0.1,并启用 localhost 级别的 Host/Origin 校验。监听 0.0.0.0 或经反向代理暴露时,必须显式配置 MCP_ALLOWED_HOSTS、MCP_ALLOWED_ORIGINS 与 MCP_API_KEY;未配置 MCP_API_KEY 时启动会打印安全警告,端点不启用鉴权。

Cloudflare Workers

pnpm worker:dev      # http://127.0.0.1:8787/mcp
pnpm worker:check    # 仅打包校验,不部署
pnpm worker:deploy   # 手动部署,仅用于调试

密钥使用 secret,不要写入 wrangler.jsonc:

wrangler secret put GPT_IMAGE_API_KEY
wrangler secret put MCP_API_KEY

非敏感配置(ALLOWED_HOSTS、ALLOWED_ORIGINS、GPT_IMAGE_BASE_URL、GPT_IMAGE_MODEL 等)可放在 Worker 的 Variables 中。日常发布使用 Cloudflare Workers Builds:连接 Git 仓库,生产分支设为 master,Build command 为 pnpm run build,Deploy command 为 npx wrangler deploy,构建环境变量只需 NODE_VERSION=26。

Worker 未启用 nodejs_compat,因此:

  • 图片默认以 base64 内联返回;

  • output_path 与本地文件路径会在请求上游之前报错;

  • 编辑图片请使用 http(s) URL 或 base64 data URI。

配置

CLI 参数优先级高于环境变量。所有 GPT_IMAGE_* 变量由服务启动时解析;非法值会直接阻止 启动并给出中文错误。

CLI 参数

环境变量

默认值

说明

--transport <stdio|http>

MCP_TRANSPORT

stdio

传输方式

--host <host>

MCP_HOST

127.0.0.1

HTTP 监听地址

--port <port>

MCP_PORT

3000

HTTP 监听端口

--path <path>

MCP_PATH

/mcp

MCP 端点路径

—

MCP_ALLOWED_HOSTS

未设置

允许的 Host 主机名,逗号分隔

—

MCP_ALLOWED_ORIGINS

未设置

允许的 Origin 主机名,逗号分隔

—

MCP_API_KEY

未设置

入站鉴权 key,逗号分隔支持多 key

—

GPT_IMAGE_BASE_URL

https://api.openai.com

自动补 /v1;拒绝带账号密码的 URL

—

GPT_IMAGE_API_KEY

回退 OPENAI_API_KEY

空字符串表示不发送 Authorization

—

GPT_IMAGE_MODEL

gpt-image-2.5-flare

生成默认模型

—

GPT_IMAGE_EDIT_MODEL

gpt-image-2.5-sunburst

编辑默认模型

—

GPT_IMAGE_RESPONSE_MODEL

gpt-6-astra

Responses 顶层文本模型

—

GPT_IMAGE_REASONING_EFFORT

high

Responses 推理强度;none 表示不发送

—

GPT_IMAGE_TIMEOUT_MS

120000

Images 请求超时(1000–900000)

—

GPT_IMAGE_RESPONSES_TIMEOUT_MS

300000

Responses 请求超时(1000–900000)

—

GPT_IMAGE_OUTPUT_ROOT

未设置

设置后 output_path 必须位于该目录

—

GPT_IMAGE_MULTI_IMAGE_FIELD

image[]

多图编辑 multipart 字段名

—

GPT_IMAGE_RESPONSE_FORMAT

未设置

附加 response_format(url/b64_json)

--help / -h

—

—

显示帮助

--version / -v

—

—

显示版本

MCP_API_KEY 使用逗号分隔,因此 key 本身不能包含逗号。Worker 侧对应 ALLOWED_HOSTS / ALLOWED_ORIGINS 变量与 MCP_API_KEY / GPT_IMAGE_* secret。

模型与尺寸

模型

quality

任意尺寸

transparent

input_fidelity

gpt-image-2 及日期快照

low/medium/high/auto

是

支持

不支持

gpt-image-2.5-flare / sunburst 及快照

low/medium/high/xhigh/max/auto

是

支持

不支持

gpt-image-1.5

low/medium/high/auto

否

支持

支持

gpt-image-1-mini

low/medium/high/auto

否

支持

仅 low

任意尺寸需满足:宽高均为 16 的倍数、比例 1:3–3:1、最长边 ≤ 3840、总像素 655,360–8,294,400;高于 2560×1440 属于实验性范围。未知的 gpt-image-* 模型只做 前缀与语法校验,便于新模型无需改代码即可透传。

数据来源

  • 请求发送到 GPT_IMAGE_BASE_URL 指向的 OpenAI 兼容服务: /v1/images/generations、/v1/images/edits、/v1/responses。

  • 图片以 base64 返回并转换为 MCP image content;只有传 output_path 时才写入本地。

  • previous_response_id 的多轮上下文由上游保存,数据保留策略由上游决定。

  • 上游 API Key 只写入请求头,不写日志、不拼进 URL;错误信息会对 key 脱敏。

  • 上游返回 data[].url 时,服务会下载并转为 base64;下载第三方存储地址时不携带 key。

开发

环境要求:Node.js >= 24.22.1,pnpm 12.15.0(由 packageManager 固定)。

pnpm install
pnpm build
pnpm lint
pnpm type-check
pnpm worker:check

构建后可用 MCP Inspector 手动调试(需要配置可用的 API Key 与 endpoint):

pnpm inspect

常用脚本:

脚本

说明

pnpm dev

tsup watch 构建

pnpm lint

ESLint 检查

pnpm lint:fix

ESLint 自动修复

pnpm format

Prettier 检查

pnpm format:fix

Prettier 格式化

pnpm type-check

TypeScript 类型检查

pnpm inspect

MCP Inspector 调试(需先构建)

pnpm worker:dev

本地 Worker 开发

pnpm worker:check

Worker 打包校验

pnpm bump

版本号、CHANGELOG、tag 与提交

pnpm commit

Commitizen 交互式提交

目录结构:

src/
├── auth.ts          # 入站 API Key 校验(常量时间比较)
├── cli.ts           # bin 入口,stdio/http 分流并注入 Node 文件能力
├── config.ts        # MCP 传输层 CLI 与环境变量解析
├── env.ts           # 列表环境变量解析(Worker 可用)
├── errors.ts        # ToolError 与错误消息工具
├── http.ts          # 共享 web-standard fetch handler(含鉴权)
├── index.ts         # 公共库 barrel
├── node.ts          # node:http + toNodeHandler
├── node-files.ts    # Node 文件读写实现(仅 cli.ts 引用)
├── server.ts        # McpServer 工厂与工具注册
├── version.ts       # 服务名与版本号
├── worker.ts        # Cloudflare Worker 入口
├── gpt-image/       # 领域层
│   ├── base64.ts    # base64 / data URI / MIME 工具
│   ├── client.ts    # GptImageApiError
│   ├── config.ts    # GPT_IMAGE_* 配置与 base URL 归一化
│   ├── files.ts     # ImageIO 接口、MIME 魔数识别
│   ├── images.ts    # Images API 生成与编辑
│   ├── inputs.ts    # URL / data URI / 本地路径解析
│   ├── models.ts    # 模型能力表与参数校验
│   ├── request.ts   # fetch 封装、超时、错误映射
│   └── responses.ts # Responses API image_generation
└── tools/
    ├── images.ts    # generate_image / edit_image
    ├── output.ts    # 落盘与结果组装
    ├── register.ts  # 统一的成功/失败结果封装
    ├── responses.ts # generate_image_via_responses
    └── schemas.ts   # 共享 zod 输入/输出 schema

新增工具时,按 src/tools/images.ts 的模式实现 registerXxxTools(server, config),在 src/server.ts 中注册,领域逻辑放入 src/gpt-image/。

http.ts、server.ts、worker.ts、env.ts、version.ts、auth.ts、tools/**、 gpt-image/** 保持 Node-free,由 ESLint no-restricted-imports 约束;Node 文件能力 node-files.ts 只由 cli.ts 注入,不会进入 Worker bundle。

Available Tools

3 tools
edit_image编辑图片A

通过 OpenAI Images API(/v1/images/edits)编辑图片,支持单图、多图、mask 与 gpt-image-2 / 2.5 系列模型。

Inputs: images (required), prompt (required), n, mask, +11 more. Returns: size, model, usage, images, +3 more

generate_image生成图片C

通过 OpenAI Images API(/v1/images/generations)生成图片,支持 gpt-image-2 与 gpt-image-2.5 系列模型。

Inputs: prompt (required), n, size, model, +8 more. Returns: size, model, usage, images, +3 more

generate_image_via_responses通过 Responses 生成图片A

通过 OpenAI Responses API 的 image_generation 工具生成图片,支持 previous_response_id 多轮编辑与参考图输入。

Inputs: prompt (required), size, model, action, +9 more. Returns: size, model, usage, images, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 3 tools

    Disambiguation4/5

    generate_image and generate_image_via_responses both create images, so there is potential overlap, but the descriptions clearly distinguish the underlying API and the multi-turn/reference-image capability. edit_image is clearly separate. An agent can choose correctly if it reads descriptions, though the generation split could still cause minor hesitation.

    Naming Consistency4/5

    All tool names follow a verb_noun pattern and are consistently snake_case. generate_image_via_responses adds a longer qualifier but remains readable and intentional. Minor deviation only.

    Tool Count5/5

    Three tools are well-scoped for an image generation/editing server: generate via one API, generate via another API with multi-turn support, and edit. Each tool earns its place without unnecessary surface area.

    Completeness4/5

    The core image lifecycle is covered: generation and editing, including masks, multiple images, references, and multi-turn editing. Some optional operations like variations or upscaling are absent, but the primary workflows are present.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI tools to uniformly discover, inspect, and call tools, prompts, and resources from multiple upstream MCP servers through a small set of fixed MCP tools, over stdio or HTTP.
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI clients such as Claude, Cursor, VS Code, and Windsurf to manage workspaces, projects, tasks, and AI agents through natural language, using a hosted OAuth-authenticated endpoint or a local stdio package. It also ships an OpenAPI codegen tool for generating MCP tools from any OpenAPI spec.
      2,530 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible clients such as Claude Desktop and Cursor to generate images and videos, synthesize speech, clone voices, and design custom voices from descriptive prompts. It supports stdio, REST, and SSE transport modes with configurable API hosts, keys, and local or URL-based resource output.
      635 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI agent or any MCP host to discover and call keyless web search, safe arithmetic, constrained HTTP fetching, and current-time tools over stdio, with model tool-calling powered by Groq's free API or local Ollama.
      MIT