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.

• Aspect Ratio Support: Use common aspect ratios like 16:9, 9:16, 1:1, landscape, portrait, etc., which automatically map to supported sizes.

• File output: Save generated images directly to disk, or receive as base64.

• AI-Generated Filenames: The AI can provide descriptive filenames like "cat-playing-football.jpg" based on the image content.

🚀 Installation

Quick Setup with NPX (Recommended)

No installation needed! Use directly with npx:

Manual Installation

Or build from source:

🔑 Configuration

The configuration shown above in the Quick Setup section works for all MCP-compatible clients:

• Claude Desktop

• VSCode

• Cursor

• Windsurf

Just add the configuration to your MCP client's config file with your OpenAI API key.

⚡ Advanced

Aspect Ratio Support

The tools now support common aspect ratios that automatically map to OpenAI's supported sizes:

• Square: 1:1, square, 4:3, 3:4 → 1024x1024

• Landscape: 16:9, landscape, 3:2 → 1536x1024

• Portrait: 9:16, portrait, 2:3 → 1024x1536

• Auto: auto → Let OpenAI choose the best size

Example: Instead of specifying size: "1536x1024", you can use size: "16:9" or size: "landscape".

Other Options

• 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:

  • macOS/Linux: Images are saved to ~/Pictures/gpt-image/ by default

  • Fallback: If the default directory cannot be created, images will be saved to /tmp (or the directory set by the MCP_HF_WORK_DIR environment variable)

  • Custom Path: You can always specify a custom file_output path to override the default

• AI-Generated Filenames:

  • The AI can provide descriptive filenames through the filename parameter (e.g., "cat-playing-football", "sunset-over-mountains")

  • Filenames are automatically sanitized to prevent security issues

  • If multiple images are generated, an index is appended (e.g., "cat-playing-football_1.jpg", "cat-playing-football_2.jpg")

• Environment Variable:

  • MCP_HF_WORK_DIR: Set this to control the fallback directory for large images and file outputs. 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