openai-image-mcp

A minimal, production-ready MCP server that exposes OpenAI GPT Image generation as two well-defined tools: generate_image (returns the PNG inline as MCP image content) and generate_image_to_file (writes the PNG to disk for asset pipelines).

Part of the mcp-accelerator: it is the reference implementation of the accelerator's "local stdio server with externalized secrets" pattern for APIs that have no official hosted MCP server.

This documentation follows the structure of a TOGAF Architecture Definition Document (ADM phases A through F), so that both humans and AI agents can extract the intent, the contracts, and the constraints without reading the code first. If you are an AI agent, start with Section 8: Agent Usage Contract.

Table of Contents

1. Architecture Vision (Phase A)

2. Business Architecture (Phase B)

3. Application Architecture (Phase C)

4. Data Architecture (Phase C)

5. Technology Architecture (Phase D)

6. Security Architecture (cross-cutting)

7. Implementation and Migration (Phases E and F)

8. Agent Usage Contract

9. Operations and Troubleshooting

Related MCP server: imagegen-mcp

1. Architecture Vision (Phase A)

1.1 Problem statement

AI assistants such as Claude can reason about images but cannot create them with OpenAI models out of the box. OpenAI offers no official hosted MCP server for its image API. Teams therefore either paste generated images around manually or build one-off integrations per project.

1.2 Vision

Provide image generation as a first-class MCP capability: any MCP host (Claude Code, Claude Desktop) gains a generate_image tool that produces brand assets, mockup imagery, placeholder art, or documentation illustrations on demand, inside the conversation, with the API key kept out of every config file.

1.3 Stakeholders and concerns

1.4 Value proposition

• One capability, two delivery modes: inline image content for conversational use, file output for build and asset pipelines.

• Zero configuration drift: the server has no config file of its own. Behavior is fully determined by the tool parameters and one environment variable.

• Small enough to audit in five minutes: a single Python module of about 75 lines.

2. Business Architecture (Phase B)

2.1 Business capability

"Generative image supply for software delivery": producing visual assets (app icons drafts, hero images, empty-state illustrations, test fixtures, blog graphics) as part of the normal engineering workflow rather than as a separate design request.

2.2 Core use cases

2.3 Value chain position

flowchart LR
    A[Requirement<br/>needs a visual] --> B[Prompt<br/>formulated by human or AI]
    B --> C[openai-image-mcp<br/>MCP tool call]
    C --> D[PNG asset]
    D --> E1[Inline review<br/>in conversation]
    D --> E2[Committed to repo<br/>asset pipeline]

3. Application Architecture (Phase C)

3.1 Component model

flowchart LR
    subgraph Host["MCP Host (Claude Code / Claude Desktop)"]
        LLM[Claude]
    end
    subgraph Server["openai-image-mcp (local process)"]
        FMCP[FastMCP runtime<br/>stdio transport]
        T1[Tool: generate_image]
        T2[Tool: generate_image_to_file]
        GEN[_generate_png<br/>validation + API call]
    end
    subgraph OpenAI["OpenAI Platform"]
        IMG[Images API<br/>model gpt-image-2]
    end
    FS[(Local filesystem)]
    KEY[/OPENAI_API_KEY<br/>env or Keychain/]

    LLM -- "JSON-RPC over stdio" --> FMCP
    FMCP --> T1 & T2
    T1 & T2 --> GEN
    GEN -- "HTTPS" --> IMG
    T2 -- "write PNG" --> FS
    KEY -. "read at process start" .-> Server

3.2 Tool catalog

3.3 Interaction (runtime view)

sequenceDiagram
    participant C as Claude (MCP host)
    participant S as openai-image-mcp
    participant O as OpenAI Images API
    C->>S: tools/call generate_image_to_file(prompt, output_path, size)
    S->>S: validate prompt not empty, size allowed, path absolute
    S->>O: images.generate(model=gpt-image-2, output_format=png)
    O-->>S: b64_json payload
    S->>S: decode, create parent dirs, write file
    S-->>C: "Image saved: /path/file.png (N bytes)"

4. Data Architecture (Phase C)

4.1 Data flows and classification

4.2 Data principles

• The server is stateless: no cache, no logs of prompts or images, no temp files.

• Prompts are transmitted to OpenAI. Do not include secrets, personal data, or unreleased confidential material in prompts.

• File writes happen only at the exact output_path the caller supplies (plus creation of missing parent directories).

5. Technology Architecture (Phase D)

5.1 Technology stack

5.2 Deployment model

The server is not deployed anywhere. Each MCP host process spawns its own instance on demand as a child process and terminates it with the session. There is nothing to operate, monitor, or patch besides the Python dependencies.

6. Security Architecture (cross-cutting)

• Fail-fast startup: the process refuses to start without OPENAI_API_KEY, so misconfiguration is caught at registration time, not at first tool call.

• No secrets at rest: config templates reference the key via ${OPENAI_API_KEY} or resolve it at launch from the macOS Keychain:

  security add-generic-password -s OPENAI_API_KEY -a "$USER" -w "sk-your-key"

• Input validation: empty prompts rejected, size restricted to an allowlist, output_path must be absolute (prevents surprises from host-dependent working directories).

• Network egress: exactly one destination, api.openai.com over HTTPS.

• Residual risk: generate_image_to_file writes wherever the caller points it. The MCP host's permission system is the guard rail for that; review file paths when approving tool calls.

7. Implementation and Migration (Phases E and F)

7.1 Installation

git clone https://github.com/rammc/openai-image-mcp.git ~/openai-image-mcp
cd ~/openai-image-mcp
uv sync

7.2 Claude Code (project scope .mcp.json)

{
  "mcpServers": {
    "openai-image": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "${HOME}/openai-image-mcp", "run", "python", "main.py"],
      "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }
    }
  }
}

Keychain variant (macOS, no shell profile changes needed):

{
  "mcpServers": {
    "openai-image": {
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "OPENAI_API_KEY=\"$(security find-generic-password -s OPENAI_API_KEY -w)\" exec uv --directory \"$HOME/openai-image-mcp\" run python main.py"
      ]
    }
  }
}

7.3 Claude Desktop (claude_desktop_config.json)

Claude Desktop does not inherit your shell environment, so use the Keychain variant above (same JSON, without the "type" field).

7.4 Verification

export OPENAI_API_KEY="sk-your-key"
uv run python main.py   # must start without error, then Ctrl+C

In Claude Code, run /mcp and confirm that openai-image is connected and lists two tools.

7.5 Migration notes

• Coming from a copy of this server with project-specific paths: only the --directory argument changes, the tool contract is identical.

• Model upgrades (for example a future gpt-image-3): single constant in main.py, no contract change expected.

8. Agent Usage Contract

This section is written for AI agents (Claude and others) so the repository is directly consumable without reading the source.

8.1 Tool contracts

generate_image(prompt: str, size: str = "auto") -> MCP Image (PNG)
generate_image_to_file(prompt: str, output_path: str, size: str = "auto") -> str

Constraints, enforced server-side with descriptive errors:

• prompt must be non-empty after trimming. Write precise, visual prompts: subject, style, composition, color, background. The prompt is sent verbatim to OpenAI.

• size must be one of: "auto", "1024x1024" (square), "1536x1024" (landscape), "1024x1536" (portrait). Any other value raises an error, including values like "512x512".

• output_path must be an ABSOLUTE path ending in a filename (use .png). Missing parent directories are created automatically.

8.2 Decision rule: which tool

• The user wants to SEE or iterate on the image in conversation: use generate_image.

• The image is an artifact of the task (belongs in a repo, a build, a document): use generate_image_to_file with a path inside the project, then reference the file. Do not use generate_image and re-save the payload manually.

8.3 Behavioral notes for agents

• Calls are synchronous and take several seconds up to about a minute. Do not retry immediately on slowness.

• Each call costs real OpenAI credits. Batch thoughtfully, do not regenerate an acceptable image just to confirm.

• Validation errors (for example "The prompt must not be empty.") mean the argument was wrong, not that the service failed. Fix the argument and retry once.

• For transparent backgrounds or specific aspect ratios beyond the three sizes, state it in the prompt; the API decides best-effort.

8.4 Example calls

generate_image(
  prompt="Flat vector illustration of a mountain trail at sunrise, warm orange and teal palette, minimal, no text",
  size="1536x1024"
)

generate_image_to_file(
  prompt="App icon draft: stylized letter M, deep red gradient background, modern, centered, no text besides the letter",
  output_path="/Users/me/project/assets/icon-draft.png",
  size="1024x1024"
)

9. Operations and Troubleshooting

License and status

MIT License, see LICENSE. Version 0.1.0. Issues and extension requests: open a GitHub issue in this repo.