This server provides an MCP interface to OpenAI's GPT-Image-1 model, enabling:
- Image Generation: Create images from text prompts with customizable size, quality, background, number of images, and output format
- Image Editing: Modify existing images using text prompts with optional masks, supporting both base64 and file paths
- Output Management: Automatically save generated/edited images to a configurable directory
- Integration: Works seamlessly with MCP-compatible clients for streamlined AI image workflows
- Reporting: Provides token usage information and comprehensive error handling with troubleshooting advice
Uses curl commands for proper MIME handling when working with image files, especially for the image editing functionality.
Runs as a Node.js application, with the MCP server requiring Node.js v14+ to function properly.
Available as an npm package that can be installed globally or run directly with npx, making it easy to integrate with various MCP clients.
Provides access to OpenAI's gpt-image-1 model for generating and editing images through text prompts, with capabilities for controlling image size, quality, background style, and output formats.
🚀 Quick Start
📋 Prerequisites
🔑 Environment Variables
💻 Example Usage with NPX
🔌 Integration with MCP Clients
🛠️ Setting Up in an MCP Client
Example Configurations for Different Operating Systems
Note: For Windows paths, use double backslashes (
\\
) to escape the backslash character in JSON. For Linux/macOS, use forward slashes (/
).
✨ Features
💡 Enhanced Capabilities
🔄 How It Works
📁 Output Directory Behavior
Installation & Usage
NPM Package
This package is available on npm: @cloudwerxlab/gpt-image-1-mcp
You can install it globally:
Or run it directly with npx as shown in the Quick Start section.
Tool: create_image
Generates a new image based on a text prompt.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
prompt | string | Yes | The text description of the image to generate (max 32,000 chars) |
size | string | No | Image size: "1024x1024" (default), "1536x1024", or "1024x1536" |
quality | string | No | Image quality: "high" (default), "medium", or "low" |
n | integer | No | Number of images to generate (1-10, default: 1) |
background | string | No | Background style: "transparent", "opaque", or "auto" (default) |
output_format | string | No | Output format: "png" (default), "jpeg", or "webp" |
output_compression | integer | No | Compression level (0-100, default: 0) |
user | string | No | User identifier for OpenAI usage tracking |
moderation | string | No | Moderation level: "low" or "auto" (default) |
Example
Response
The tool returns:
- A formatted text message with details about the generated image(s)
- The image(s) as base64-encoded data
- Metadata including token usage and file paths
Tool: create_image_edit
Edits an existing image based on a text prompt and optional mask.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
image | string, object, or array | Yes | The image(s) to edit (base64 string or file path object) |
prompt | string | Yes | The text description of the desired edit (max 32,000 chars) |
mask | string or object | No | The mask that defines areas to edit (base64 string or file path object) |
size | string | No | Image size: "1024x1024" (default), "1536x1024", or "1024x1536" |
quality | string | No | Image quality: "high" (default), "medium", or "low" |
n | integer | No | Number of images to generate (1-10, default: 1) |
background | string | No | Background style: "transparent", "opaque", or "auto" (default) |
user | string | No | User identifier for OpenAI usage tracking |
Example with Base64 Encoded Image
Example with File Path
Response
The tool returns:
- A formatted text message with details about the edited image(s)
- The edited image(s) as base64-encoded data
- Metadata including token usage and file paths
🔧 Troubleshooting
🚨 Common Issues
🔍 Error Handling and Reporting
The MCP server includes comprehensive error handling that provides detailed information when something goes wrong. When an error occurs:
- Error Format: All errors are returned with:
- A clear error message describing what went wrong
- The specific error code or type
- Additional context about the error when available
- AI Assistant Behavior: When using this MCP server with AI assistants:
- The AI will always report the full error message to help with troubleshooting
- The AI will explain the likely cause of the error in plain language
- The AI will suggest specific steps to resolve the issue
📄 License
🙏 Acknowledgments
You must be authenticated.
A Model Context Protocol server that enables generating and editing images using OpenAI's gpt-image-1 model, allowing AI assistants to create and modify images from text prompts.
- 📋 Prerequisites
- 🔑 Environment Variables
- 💻 Example Usage with NPX
- 🔌 Integration with MCP Clients
- ✨ Features
- 🔄 How It Works
- Installation & Usage
- 🔧 Troubleshooting
- 📄 License
- 🙏 Acknowledgments
Related Resources
Related MCP Servers
- AsecurityFlicenseAqualityA Model Context Protocol server that provides image generation capabilities using the Ideogram API, allowing users to create images from text prompts with customizable parameters.Last updated -1973TypeScript
- -security-license-qualityA Model Context Protocol server enabling AI assistants to generate images through OpenAI's DALL-E API with full support for all available options and fine-grained control.Last updated -JavaScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to generate images, text, and audio through the Pollinations APIs without requiring authentication.Last updated -73254JavaScriptMIT License
- -securityAlicense-qualityAn MCP tool server that enables generating and editing images through OpenAI's image models, supporting text-to-image generation and advanced image editing (inpainting, outpainting) across various MCP-compatible clients.Last updated -19TypeScriptMIT License