gpt-image-2-mcp
An MCP server that exposes OpenAI's gpt-image-2 (released 2026-04-21) to any MCP client — Claude Desktop, Claude Code, Cursor, MCP Inspector, etc.
Six tools:
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
An MCP server that exposes OpenAI's gpt-image-2 (released 2026-04-21) to any MCP client — Claude Desktop, Claude Code, Cursor, MCP Inspector, etc.
Six tools:
MCP server exposing OpenAI's gpt-image-2 for image generation and iterative editing
generate_image | text → image |
edit_image | 1–8 reference images (+ optional mask) → image |
start_edit_session | begin an iterative multi-turn edit |
continue_edit_session | apply another refinement turn — previous output becomes the new input |
end_edit_session | release a session |
list_edit_sessions | show active sessions |
Every generated image is saved to disk and returned inline so the calling model sees it.
openai v7)gpt-image-2 access (Organization Verification may be required)pnpm install
pnpm run build
This produces build/index.js, which is the server entry point.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"gpt-image-2": {
"command": "node",
"args": ["/absolute/path/to/gpt_image_2_mcp/build/index.js"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}
Either add to ~/.claude.json under mcpServers with the same shape, or drop an .mcp.json next to your project:
{
"mcpServers": {
"gpt-image-2": {
"command": "node",
"args": ["/absolute/path/to/gpt_image_2_mcp/build/index.js"],
"env": { "OPENAI_API_KEY": "sk-..." }
}
}
}
pnpm run inspect
Launches the official inspector UI pointed at your local build.
Unless overridden, each tool writes to:
<OS config dir>/gpt-image-2-mcp/output/<project-name>-<hash>/
~/.config/gpt-image-2-mcp/output/<project>-<hash>/%APPDATA%\gpt-image-2-mcp\output\<project>-<hash>\<project>-<hash> is derived from the git root (if any) or the current working directory — each project gets its own folder so generations don't collide.
Per-call override: pass output_dir: "/some/path" to any tool.
Filenames look like image-20260422-150301-a1b2c3.png. If you pass filename_prefix: "hero-banner", it becomes image-20260422-150301-a1b2c3-hero-banner.png.
Every tool result contains:
ImageContent block per generated image (so the LLM sees the image)structuredContent for programmatic consumers:{
"model": "gpt-image-2",
"prompt": "…",
"requested": { "size": "auto", "quality": "auto", "n": 1, "format": "png" },
"applied": { "size": "1024x1024", "quality": "high", "background": "opaque", "output_format": "png" },
"images": [ { "file_path": "…", "filename": "…", "size_bytes": 123456, "mime_type": "image/png" } ],
"usage": { "input_tokens": …, "output_tokens": …, "total_tokens": …, "input_tokens_details": { … } },
"cost_usd_estimated": 0.2112
}
Session tools additionally return session_id and turn.
Default is auto (the model picks). You can pass:
1024x1024, 1536x1024, 1024x1536WxH where:
Invalid sizes fail before the API call with a clear error — no wasted requests.
Pass background: "transparent" to any generate or edit tool to get an alpha channel.
OpenAI added transparency to gpt-image-2 on 2026-08-20 and still labels it preview. Two rules:
output_format must be png or webp. JPEG has no alpha channel, and the API rejects the combination with 400 invalid_transparent_background_output_format. This server checks it first and returns a clear tool error instead.continue_edit_session the check uses the effective format — if you omit output_format, the session's own format applies, so a JPEG session rejects a transparent request rather than failing at OpenAI.The other two values are unchanged: auto (default, model decides) and opaque (always filled).
Versions ≤ 0.3.0 of this server refused
transparentoutright, because gpt-image-2 genuinely did not support it before 2026-08-20.
start_edit_session prompt: "A coastal lighthouse at dawn, photorealistic", images: ["./sketch.png"]
→ session_id: edit-1761149123-a1b2c3d4, turn 1, saved to …/session-…-turn1.png
continue_edit_session session_id: "edit-…-a1b2c3d4", prompt: "Make the sky more orange. Keep everything else the same."
→ turn 2
continue_edit_session session_id: "edit-…-a1b2c3d4", prompt: "Add a small boat on the horizon."
→ turn 3
end_edit_session session_id: "edit-…-a1b2c3d4"
Sessions are in-memory only and discarded on server restart — this is intentional (keeps the server stateless on the wire) and mirrors the Gemini MCP pattern.
edit_image and start_edit_sessionAccepts any mix of:
/Users/me/photo.png./photo.png (resolved from CWD)file:///Users/me/photo.pnghttps://example.com/photo.png (downloaded, size-capped)data:image/png;base64,iVBOR…Up to 8 images per call. Each ≤ 50MB. PNG/WEBP/JPG supported.
The server ships no hard spending limits — you should watch your OpenAI usage dashboard. Each tool result includes an estimated cost in USD computed from the token usage returned by the API, plus an approximate pre-flight estimate logged to stderr.
Rough per-image cost at common sizes:
Custom sizes scale with pixel count. Edit calls additionally tokenize input images at high fidelity — large reference images are expensive.
edit_image, start_edit_session, and continue_edit_session call POST /v1/images/edits directly. This is the canonical endpoint: it supports n > 1, masks, and returns accurate per-call token usage for cost estimation.
History: at launch (2026-04-21) the endpoint rejected
gpt-image-2(andgpt-image-1.5) with400 Invalid value: 'gpt-image-2'. Value must be 'dall-e-2'.— an OpenAI-side bug. Versions ≤ 0.2.0 of this server therefore routed edits through the Responses API by default. OpenAI fixed the endpoint silently in early May 2026 (verified live 2026-06-11), and since 0.3.0 the direct endpoint is the default again.
The Responses-API workaround is kept as a fallback (src/utils/edit-via-responses.ts):
OPENAI_FORCE_RESPONSES_EDITS=1 to pin it explicitly.OPENAI_USE_DIRECT_EDITS toggle from 0.2.0 is deprecated and ignored (its only meaningful setting was 1 — opt into the direct endpoint, which is now the default).Fallback mechanics: input images are uploaded via the Files API (purpose: "vision"), a cheap host model (default gpt-4.1-mini, override with OPENAI_RESPONSES_EDIT_MODEL) is forced to invoke the image_generation tool, the base64 result is extracted, and uploaded files are deleted afterwards.
Fallback trade-offs versus the direct endpoint (only apply when the fallback is active — the tool result carries route: "responses" and a note when they do):
n > 1 is not supported — the Responses path returns one image per call.usage only reports the host chat model's text tokens; the image tool is billed separately (~$0.04–0.05 extra for a 1024×1536 medium edit).input_image_mask.file_id.env block of your MCP config.403 / organization verification — gpt-image-2 may require Organization Verification on your OpenAI org. Check the dashboard.429 — you hit the IPM (images per minute) cap for your tier. Lower n, or wait.src/**/*.ts — all logs must use utils/logger.ts (stderr). This is the single biggest MCP footgun.pnpm run dev # tsx watch
pnpm run typecheck # tsc --noEmit
pnpm run build # compile to build/
pnpm run inspect # launch MCP Inspector
MIT
MCP server exposing OpenAI's gpt-image-2 for image generation and iterative editing
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Gpt Image 2 透過 stdio 在本機執行。
上次檢查時間:2026-11-05。 MCP server exposing OpenAI's gpt-image-2 for image generation and iterative editing