Openai Image Generator

🚀 openai-gpt-image-mcp

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

🚀 Quick Start

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

• Generate images using text prompts.
• Edit images (including inpainting, outpainting, compositing) through advanced prompt control.
• Support: Claude Desktop, Cursor, VSCode, Windsurf, and any MCP-compatible clients.

✨ Features

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

📦 Installation

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

📚 Documentation

🔑 Configuration

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

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

⚡ Advanced Features

• 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 the edit is applied.
• Check src/index.ts for all options.

🧑‍💻 Development

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

🩺 Troubleshooting

• Ensure your OPENAI_API_KEY is valid and has access to the image API.
• You must have a verified OpenAI organization. After verification, image API access may take 15–20 minutes to activate.
• File paths must be absolute.
  • Unix/macOS/Linux: Start with / (e.g., /path/to/image.png).
  • Windows: Follow the drive letter with : (e.g., C:/path/to/image.png or C:\path\to\image.png).
• For file output, ensure the directory is writable.
• If you encounter file type-related errors, check the image file's extension and format.

⚠️ Limitations and Large File Handling

• 1MB payload limit: MCP clients (including Claude Desktop) have a strict 1MB upper limit on tool responses. Large images (especially high-resolution or multiple images) can easily exceed this limit when returned as base64.
• Automatic switch to file output: If the total image size exceeds 1MB, the tool will automatically save the images to disk and return the file paths instead of base64. This ensures compatibility and prevents errors like Result exceeds maximum length 1048576.
• Default file location: If you don't specify a file_output path, images will be saved to a unique file name in /tmp (or the directory set by the MCP_HF_WORK_DIR environment variable).
• Environment variables:
  • MCP_HF_WORK_DIR: Set this variable to control the location of large images and file outputs. Example: export MCP_HF_WORK_DIR=/your/desired/dir.
• Best practice: For large or production-use images, always use file output and ensure the client is configured to handle file paths.

📄 License

MIT

💡 Usage Tip

If you have any questions or feedback, please contact SureScale.ai.