OpenAI Image

@mindstone/mcp-server-openai-image

[npm version] [License: FSL-1.1-MIT]

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: <workspace>/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

[Add to Cursor] [Add to VS Code] [Add to VS Code Insiders]

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

{  "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-imagenpm installnpm 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 <workspace>/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 (OpenAI's most capable image model). gpt-image-2.5-flare is faster at the same token price. The 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": ["<path-to-repo>/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 is applied to the generated-image output directory before any write, matching the host's built-in Write tool.
• Reads are open-then-validate, with the fence decision bound to the opened inode: after the fence approves the canonical path, the connector opens a descriptor, verifies via fstat that the opened inode agrees with the baseline stat, then re-resolves the canonical path post-open (requiring it to be byte-identical to the fence-approved path) and lstat-checks that it still names the pinned inode — a swap-back that flips the leaf to a symlink between the two is exposed rather than followed. On Linux the descriptor itself is then resolved via /proc/self/fd/<fd> (the kernel's canonical path for the pinned inode, immune to any pathname race) and containment is re-checked on that. Reads flow through the pinned descriptor, so a path swap at any point fails closed with WORKSPACE_FENCE_VIOLATION. Platform note: on macOS/Windows (no /proc, and Node exposes no openat/F_GETPATH) a narrow residual remains — a local attacker who atomically swaps an in-workspace directory component in the instant between the post-open re-resolution and the identity check can redirect that check. It is practical only when the target file sits on a different filesystem than the workspace (otherwise a plain hard link defeats the fence with no race at all — a pre-existing platform limitation of canonical-prefix containment, on all OSes), and every failed attempt surfaces as a visible fence-violation error. On Linux this class is closed completely.
• Writes never re-trust the validated pathname: after the fence approves the output directory's canonical path (re-checked in full once mkdir has materialised it), the bytes are staged in a fresh, unpredictable mkdtemp directory (mode 0700) created atomically inside the canonical directory — which contains no symlink components, so a check-then-use symlink swap of any path component cannot redirect the write. The file is opened wx (mode 0600), written through a single descriptor, then hard-linked into place (link fails with EEXIST if the destination name is taken, by a real file or a planted symlink; filesystems without hard-link support fall back to an exclusive create at the destination). The directory's canonical identity is re-verified before any bytes flow — before the staging write, immediately before and after the hard link, and before and after the fallback's exclusive create; a mid-flight swap fails closed with WORKSPACE_FENCE_VIOLATION and the staging directory is removed.
• Fence errors name the model-supplied input path and the workspace root only — never the canonical realpath of a symlink target — so the agent can self-correct without leaking the linked-Space destination. Caller-controlled values echoed into errors (tool-input paths, the configured model) are enclosed in an <untrusted-content source="…"> envelope with close-tag breakout escaping (see src/untrusted-content.ts), so a crafted value cannot terminate the result envelope.
• Upstream success payloads are schema-validated (a malformed body fails closed with NETWORK_ERROR), and returned image bytes must carry the requested format's magic bytes — mismatched payloads are rejected with INVALID_IMAGE_DATA rather than saved under a false extension/MIME type. Upstream error bodies and status text are used for classification only and never reach model-visible errors.
• Generated files are written with mode 0o600.
• OPENAI_API_KEY values are scrubbed from logs, structured error payloads, and stack traces — see src/index.ts sanitizeUserFacingText.
• Prompts and absolute file paths are redacted from log output by default; only metadata (counts, sizes, timings, status codes) is logged.
• The OpenAI API base URL is hard-pinned to https://api.openai.com; there is no env override.

Legacy folder migration

Hosts that previously used a folder named RebelImages/ under the workspace will see a one-time symlink-safe rename to MCP-Generated-Images/ on first run. The migration is idempotent and skips when the target already exists; symlinks at either path abort the rename. The migration exists only to preserve existing user files; new installs go straight to MCP-Generated-Images/.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.