Overview

This MCP (Model Context Protocol) server exposes OpenAI GPT-4o / gpt-image-1 image generation and editing capabilities to any MCP-compatible client (for example Claude Desktop, Cursor, VSCode, Windsurf). It acts as a local tool server that translates MCP tool calls into OpenAI Images API requests and returns results in a format MCP clients expect — either inline base64 or file paths for large outputs.

The server is useful when you want safe, scalable image generation/editing integrated directly into AI assistants or editor extensions without embedding OpenAI keys into the client. It handles common image workflows (generation, inpainting, outpainting, compositing), large-payload handling (auto-saving large images to disk), and supports both OpenAI and Azure OpenAI endpoints.

Features

Generate images from text prompts using GPT-4o / gpt-image-1.
Edit images with masks (inpainting/outpainting) using a prompt + optional mask.
Return images as base64 or save to disk and return file paths when payloads exceed MCP limits.
Support for Azure OpenAI deployments (endpoint + API version).
Configurable working directory for file outputs (MCP_HF_WORK_DIR).
Works with MCP clients (Claude Desktop, Cursor, VSCode extensions, Windsurf).
Built in TypeScript; easy to inspect and extend (src/index.ts).

Installation / Configuration

Clone, install, build and run:

git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build
node dist/index.js

Minimal MCP server config (example for a client like Claude Desktop or VSCode):

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Azure OpenAI example:

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "AZURE_OPENAI_API_KEY": "sk-...",
        "AZURE_OPENAI_ENDPOINT": "https://my.azure.endpoint",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

Use an environment file:

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
    }
  }
}

Environment variables

Variable	Description
OPENAI_API_KEY	Standard OpenAI API key for image APIs
AZURE_OPENAI_API_KEY	Azure OpenAI key (when using Azure)
AZURE_OPENAI_ENDPOINT	Azure endpoint host (when using Azure)
OPENAI_API_VERSION	API version for Azure (e.g., 2024-12-01-preview)
MCP_HF_WORK_DIR	Directory to save large images / file outputs (defaults to /tmp on Unix)

Available Tools

The server exposes two primary MCP tools:

create-image
- Input: prompt, n (number of images, up to 10), size/quality options, background
- Output: base64 images or file paths (if large)
edit-image
- Input: prompt, source image (file path or base64), optional mask (file path or base64), n
- Output: edited images as base64 or file paths

Typical parameters:

prompt: string
n: integer (1..10)
size: e.g., “1024x1024”
file_output: optional absolute path or directory
mask: image file path or base64 for targeted edits

See src/index.ts for the full list of supported options and defaults.

Use Cases

Generate marketing mockups:
- Request 4 variations of a 1024x1024 product render by setting prompt and n=4. The server returns base64 if small or file paths if files exceed 1MB.
Inpaint a photo:
- Provide a source image and a mask to edit only a region (e.g., remove an object or paint new sky). Use edit-image with mask specified as a file path.
Automated image pipeline in an editor:
- Configure the MCP server in VSCode. Trigger image generation from a comment or command palette; saved images are stored to MCP_HF_WORK_DIR and referenced from the editor.
Azure deployment:
- Use Azure keys and OPENAI_API_VERSION to route requests through an Azure OpenAI instance while keeping client-side credentials out of the editor.

Example create-image payload (conceptual):

{
  "tool": "create-image",
  "prompt": "A serene mountain lake at sunrise, photorealistic",
  "n": 2,
  "size": "1024x1024",
  "file_output": "/absolute/path/to/output"
}

Limitations & Large File Handling

MCP clients often impose a ~1MB response limit. To avoid failures, this server:
- Automatically switches to saving images to disk and returns file paths when combined image payloads exceed 1MB.
- Uses MCP_HF_WORK_DIR (or /tmp by default) for temporary output.
Always use absolute file paths for inputs/outputs (Unix-style: /path/to/file; Windows: C:/path/to/file).

Troubleshooting

Ensure your OPENAI_API_KEY has access to image APIs and your organization is verified; activation for image access can take ~15–20 minutes.
If you get “result exceeds maximum length of 1048576”, switch to file_output or increase use of file paths.
Make sure output directories are writable by the process user.
Verify image file formats/extensions match expected types (PNG/JPEG).

Development

Source: TypeScript (src/index.ts)
Build: yarn build
Run locally: node dist/index.js
Inspect or extend the tool handlers to add parameters or integrate logging/monitoring.

References

OpenAI Images API: https://platform.openai.com/docs/api-reference/images
MCP SDK (Model Context Protocol): @modelcontextprotocol/sdk

License

MIT (see repository LICENSE file)

OpenAI GPT Image MCP Server for GPT-4o APIs