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.

⚡ 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.
• Provide an environment file with --env-file path/to/file/.env
• See src/index.ts for all options.

🧑‍💻 Development

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

📝 License

MIT

⚠️ 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
• Contributions from Axle Research and Technology

🚀 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-..." }
    }
  }
}

Also supports Azure deployments:

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

Also supports supplying an environment files:

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

🩺 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.