OpenAI Image

@mindstone/mcp-server-openai-image

OpenAI image generation MCP server — text-to-image and image edits via OpenAI's gpt-image-2.5 models, with sharp text rendering, multilingual prompts, four quality levels, and three aspect ratios.

*Workspace-sandboxed OpenAI image MCP. Generated PNGs land under MCP_WORKSPACE_PATH only, every error returns a structured recovery code, and the API key is hard-pinned to api.openai.com.*

Status

• Version: 0.4.0 · npm
• Auth: API key (OPENAI_API_KEY)
• Tools: 2 (image generation, image editing)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

When we started this connector in early 2026, OpenAI had not published an MCP server for its image-generation surface and the available community options either embedded their own download daemons or wrote generated bytes to unconstrained paths on the host. We wrote our own so that an MCP host could call generate_image and edit_image with the same sandboxing, recovery-contract, and key-handling guarantees we apply across the rest of this repository — saved PNGs land under a realpath-fenced workspace, every error is returned as a structured { ok, code, error, resolution } object, and the OpenAI API key is hard-pinned to https://api.openai.com so an attacker-controlled environment cannot redirect prompts, image bytes, or the bearer token elsewhere.

Example interaction

"Generate a 1024x1536 portrait of a Belgian draft horse pulling a brewery cart in soft morning light."

Tools the host calls:

1. generate_image — submits the prompt with size: portrait, quality: high, count: 1.

Response (trimmed):

{

"ok": true, "saved_paths": [ "/Users/me/workspace/Chief-of-Staff/generated-images/20260519-1530-a1b2c3.png" ], "model": "gpt-image-2.5-sunburst", "size": "1024x1536", "quality": "high" }

On failure:

{

"ok": false, "code": "WORKSPACE_FENCE_VIOLATION", "error": "Reference image is outside your workspace and folders linked as Spaces. Path: /linked.png. Workspace: /Users/me/workspace.", "resolution": "Move or copy the file into your workspace or a folder linked as a Space, then try again." }

Requirements

• Node.js 20.3+
• npm
• An OpenAI API key with image generation access

One-click install

After clicking the button, your host will prompt you to fill: OPENAI_API_KEY, OPENAI_IMAGE_MODEL, OPENAI_IMAGE_REQUEST_TIMEOUT_MS.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (OpenAI Image)

{

"mcpServers": { "OpenAI Image": { "command": "npx", "args": [ "-y", "@mindstone/mcp-server-openai-image" ], "env": { "OPENAI_API_KEY": "", "OPENAI_IMAGE_MODEL": "gpt-image-2.5-sunburst", "OPENAI_IMAGE_REQUEST_TIMEOUT_MS": "180000" } } } }

Quick Start

Install & build

cd <path-to-repo>/connectors/openai-image

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-openai-image

Local

node dist/index.js

Configuration

Environment variables

• OPENAI_API_KEY — OpenAI API key. Required for tool calls; if absent, the server starts in *unconfigured* mode and each tool call returns a structured NOT_CONFIGURED response instead of crashing.
• MCP_WORKSPACE_PATH — optional workspace path. Generated images are written under /Chief-of-Staff/generated-images/. Defaults to ~/Pictures/MCP-Generated-Images/ when unset.
• OPENAI_IMAGE_MODEL — optional model override. Defaults to gpt-image-2.5-sunburst. The known list now also includes gpt-image-2.6-sunburst and gpt-image-2.6-flare; gpt-image-2.5-flare is faster at the same token price. The full known list lives in src/models.ts; other values are passed through to OpenAI and log a warning.
• OPENAI_IMAGE_REQUEST_TIMEOUT_MS — optional override (positive integer ms, max 30 min) for the OpenAI image API timeout. Default: 180000 (3 min). Sized for quality: 'high' generation, which OpenAI documents as taking up to ~2 min for complex prompts; lower for tighter bounds.
• MCP_ALLOWED_SYMLINK_ROOTS — optional JSON array of absolute paths. The connector reads (and writes generated images) through in-workspace symlinks whose canonical targets land inside MCP_WORKSPACE_PATH or one of these declared roots — the same roots the host's built-in file tools trust for declared Spaces. Fail-closed: if the value is missing, empty, malformed JSON, not an array, or any entry is non-string / empty / relative, the whole value is rejected and the connector falls back to strict workspace-only containment with one structured stderr warning. Standalone OSS users omit it; Rebel's host injects it automatically from your declared Spaces.
• MCP_HTTP_PORT — optional. When set, the server speaks MCP over HTTP on this port bound to 127.0.0.1 (loopback only, non-loopback Host headers are rejected) instead of stdio. Intended for host-managed local deployments; stdio hosts omit it.

Host configuration examples

Claude Desktop / Cursor

{

"mcpServers": { "OpenAIImage": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-openai-image"], "env": { "OPENAI_API_KEY": "your-openai-api-key" } } } }

Mindstone Rebel

Use the catalog entry in Rebel's connector picker. Rebel injects OPENAI_API_KEY from your configured provider keys and points MCP_WORKSPACE_PATH at your active workspace.

Local development (no npm publish needed)

{

"mcpServers": { "OpenAIImage": { "command": "node", "args": [" /connectors/openai-image/dist/index.js"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace" } } } }

Tools (2)

generate_image

Inputs:

• prompt (string, required) — text description of the image to generate.
• size (square | portrait | landscape, optional) — 1024x1024, 1024x1536, 1536x1024.
• quality (low | medium | high | auto, optional) — defaults to high. Medium is usually about 10-20 seconds and $0.01-0.02; high usually takes 20-60 seconds and costs about $0.05-0.08 (measured on gpt-image-2.5). Lower quality is dramatically cheaper.
• count (integer 1–8, optional) — defaults to 1. Cost scales linearly with count.
• moderation (auto | low, optional) — content moderation strictness, defaults to auto. low weakens OpenAI's content filtering on your account and is passed through like any other tool input; invocation gating is the host's tool-approval layer's job.
• output_format (png | jpeg | webp, optional) — output file format, defaults to png. The saved filename extension and inline preview MIME type follow the chosen format (.png / .jpg / .webp).
• output_compression (integer 0–100, optional) — compression level; only valid with jpeg or webp output. Combining it with png fails fast with a structured INVALID_INPUT error before any API call.
• background (transparent | opaque | auto, optional) — background style. transparent produces a cutout with an alpha channel and requires png/webp output plus a transparency-capable model. Both gpt-image-2.5 models (the default included) support it; gpt-image-2 and its dated snapshots reject transparent backgrounds upstream, so with that override the tool fails fast with INVALID_INPUT and a resolution pointing at OPENAI_IMAGE_MODEL=gpt-image-2.5-sunburst. Unknown model overrides are passed through to upstream validation, matching the connector's existing OPENAI_IMAGE_MODEL philosophy.

Returns a text content block with the saved path(s) plus up to 5 inline image content blocks. On failure, returns a structured { ok: false, code, error, resolution } response. The tool is annotated destructiveHint: true, openWorldHint: true, idempotentHint: false.

edit_image

Inputs:

• prompt (string, required) — what to change about the input images.
• image_paths (array of 1–4 absolute file paths, required) — source images. Each path is validated: it must resolve lexically inside MCP_WORKSPACE_PATH, and its canonical realpath must land inside the canonical workspace or one of the declared roots in MCP_ALLOWED_SYMLINK_ROOTS (matching the host's built-in file-tool containment). Paths outside both are rejected with WORKSPACE_FENCE_VIOLATION before any read.
• mask_path (PNG path, optional) — alpha-channel mask indicating which area to edit.
• size, quality, count, moderation, output_format, output_compression, background — same shape as generate_image.

Returns the same content shape as generate_image. Same destructiveHint / openWorldHint / idempotentHint annotations.

Recovery contract

Every tool error is returned as structured JSON with these fields:

{

"ok": false, "code": "NOT_CONFIGURED | INVALID_API_KEY | RATE_LIMITED | CONTENT_POLICY | WORKSPACE_FENCE_VIOLATION | MODEL_UNAVAILABLE | NETWORK_ERROR | TIMEOUT | WRITE_FAILED | INVALID_INPUT | INVALID_IMAGE_DATA", "error": "Human-readable message", "resolution": "Concrete next step for the operator" }

The structured shape lets agentic hosts route to recovery flows rather than surfacing raw exception text.

Security notes

• Tool inputs that name local files (edit_image.image_paths, edit_image.mask_path) pass through a two-gate fence before any read: a lexical workspace pre-gate (the path must resolve lexically inside MCP_WORKSPACE_PATH), then a canonical containment gate (the path's realpath must land inside the canonical workspace or one of the declared roots in MCP_ALLOWED_SYMLINK_ROOTS, judged by path.relative segment semantics — never startsWith). Paths outside both are rejected with WORKSPACE_FENCE_VIOLATION to prevent symlink-escape and traversal. The same containment