@mindstone/mcp-server-openai-image

OpenAI image generation MCP server — text-to-image and image edits via OpenAI's gpt-image-2, 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.2.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",
  "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

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",
        "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 <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.
• 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.

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 50 seconds and $0.04; high can take up to 3 minutes and cost about $0.21. 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.

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 — 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_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.
• 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.
• 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.