What is Openai Gpt Image Mcp

openai-gpt-image-mcp is a Model Context Protocol (MCP) tool server designed for OpenAI’s GPT-4o/gpt-image-1 image generation and editing APIs, enabling users to create and modify images based on text prompts.

Use cases

Use cases include generating artwork from descriptions, editing existing images based on user input, and creating visual content for marketing or social media.

How to use

To use openai-gpt-image-mcp, clone the repository from GitHub, navigate to the project directory, and run the installation commands using yarn. After installation, you can generate and edit images by sending appropriate prompts to the server.

Key features

Key features include image generation from text prompts with customizable options, advanced image editing capabilities (inpainting, outpainting, compositing), and support for various MCP-compatible clients.

Where to use

openai-gpt-image-mcp can be used in various fields such as graphic design, content creation, game development, and any application that requires image generation or editing.

Hosted by Modl, any commits or changes made by the Modl team is to ensure compatibility

openai-gpt-image-mcp

A Model Context Protocol (MCP) tool server for OpenAI’s GPT-4o/gpt-image-1 image generation and editing APIs.

• Generate images from text prompts using OpenAI’s latest models.
• Edit images (inpainting, outpainting, compositing) with advanced prompt control.
• Supports: Claude Desktop, Cursor, VSCode, Windsurf, and any MCP-compatible client.

✨ Features

• create-image: Generate images from a prompt, with advanced options (size, quality, background, etc).
• edit-image: Edit or extend images using a prompt and optional mask, supporting both file paths and base64 input.
• File output: Save generated images directly to disk, or receive as base64.

🚀 Installation

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

🔑 Configuration

Add to Claude Desktop or VSCode (including Cursor/Windsurf) config:

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

⚡ Advanced

• For create-image, set n to generate up to 10 images at once.
• For edit-image, provide a mask image (file path or base64) to control where edits are applied.
• See src/index.ts for all options.

🧑‍💻 Development

• TypeScript source: src/index.ts
• Build: yarn build
• Run: node dist/index.js

📝 License

MIT

🩺 Troubleshooting

• Make sure your OPENAI_API_KEY is valid and has image API access.
• You must have a verified OpenAI organization. After verifying, it can take 15–20 minutes for image API access to activate.
• File paths must be absolute.
  • Unix/macOS/Linux: Starting with / (e.g., /path/to/image.png)
  • Windows: Drive letter followed by : (e.g., C:/path/to/image.png or C:\path\to\image.png)
• For file output, ensure the directory is writable.
• If you see errors about file types, check your image file extensions and formats.

⚠️ Limitations & Large File Handling

• 1MB Payload Limit: MCP clients (including Claude Desktop) have a hard 1MB limit for tool responses. Large images (especially high-res or multiple images) can easily exceed this limit if returned as base64.
• Auto-Switch to File Output: If the total image size exceeds 1MB, the tool will automatically save images to disk and return the file path(s) instead of base64. This ensures compatibility and prevents errors like result exceeds maximum length of 1048576.
• Default File Location: If you do not specify a file_output path, images will be saved to /tmp (or the directory set by the MCP_HF_WORK_DIR environment variable) with a unique filename.
• Environment Variable:
  • MCP_HF_WORK_DIR: Set this to control where large images and file outputs are saved. Example: export MCP_HF_WORK_DIR=/your/desired/dir
• Best Practice: For large or production images, always use file output and ensure your client is configured to handle file paths.

📚 References

• OpenAI Images API Documentation

🙏 Credits

• Built with @modelcontextprotocol/sdk
• Uses openai Node.js SDK
• Built by SureScale.ai