@cloudwerxlab/gpt-image-1-mcp
A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.
Quick Start
Run this MCP server directly using NPX without installing it. View on npm.
npx -y @cloudwerxlab/gpt-image-1-mcp
The -y flag automatically answers "yes" to any prompts that might appear during the installation process.
Prerequisites
 Node.js (v14 or higher) |
 OpenAI API key with access to gpt-image-1 |
Environment Variables
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |  Yes | Your OpenAI API key with access to the gpt-image-1 model |
GPT_IMAGE_OUTPUT_DIR |  No | Custom directory for saving generated images (defaults to user's Pictures folder under gpt-image-1 subfolder) |
Example Usage with NPX
| Operating System | Command Line Example |
|---|---|
| Linux/macOS | |
| Windows (PowerShell) | |
| Windows (Command Prompt) | |
Integration with MCP Clients
Setting Up in an MCP Client
Step 1: Locate Settings File
|
Step 2: Add ConfigurationAdd the following configuration to the |
{
"mcpServers": {
"gpt-image-1": {
"command": "npx",
"args": [
"-y",
"@cloudwerxlab/gpt-image-1-mcp"
],
"env": {
"OPENAI_API_KEY": "PASTE YOUR OPEN-AI KEY HERE",
"GPT_IMAGE_OUTPUT_DIR": "OPTIONAL: PATH TO SAVE GENERATED IMAGES"
}
}
}
}
Example Configurations for Different Operating Systems
| Operating System | Example Configuration |
|---|---|
| Windows | |
| Linux/macOS | |
Note: For Windows paths, use double backslashes (
\) to escape the backslash character in JSON. For Linux/macOS, use forward slashes (/).
Features
|
|
Core Tools
Enhanced Capabilities
|
|
Output & Formatting
Configuration & Handling
How It Works
 Image Generation |  Image Editing |
|---|---|
|
|
Output Directory Behavior
|
|
Storage Location
Default Location: User's Pictures folder under 
File ManagementInstallation & Usage
NPM Package
This package is available on npm: @cloudwerxlab/gpt-image-1-mcp
You can install it globally:
npm install -g @cloudwerxlab/gpt-image-1-mcp
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
<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
"prompt": "A futuristic city skyline at sunset, digital art",
"size": "1024x1024",
"quality": "high",
"n": 1,
"background": "auto"
}
</arguments>
</use_mcp_tool>
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
<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image_edit</tool_name>
<arguments>
{
"image": "BASE64_ENCODED_IMAGE_STRING",
"prompt": "Add a small robot in the corner",
"mask": "BASE64_ENCODED_MASK_STRING",
"quality": "high"
}
</arguments>
</use_mcp_tool>
Example with File Path
<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image_edit</tool_name>
<arguments>
{
"image": {
"filePath": "C:/path/to/your/image.png"
},
"prompt": "Add a small robot in the corner",
"mask": {
"filePath": "C:/path/to/your/mask.png"
},
"quality": "high"
}
</arguments>
</use_mcp_tool>
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
| Issue | Solution |
|---|---|
| Ensure image files have the correct extension (.png, .jpg, etc.) that matches their actual format. The server uses file extensions to determine MIME types. |
| Verify your OpenAI API key is correct and has access to the gpt-image-1 model. Check for any spaces or special characters that might have been accidentally included. |
| Ensure you have the correct TypeScript version installed (v5.3.3 or compatible) and that your |
| Check if the process has write permissions to the configured output directory. Try using an absolute path for |
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
This project is licensed under the MIT License - see the LICENSE file for details.
License Summary
The MIT License is a permissive license that is short and to the point. It lets people do anything with your code with proper attribution and without warranty.
You are free to:
- Use the software commercially
- Modify the software
- Distribute the software
- Use and modify the software privately
Under the following terms:
- Include the original copyright notice and the license notice in all copies or substantial uses of the work
Limitations:
- The authors provide no warranty with the software and are not liable for any damages
Acknowledgments
Report Bug • Request Feature • Visit Our Website
Developed with 
by CLOUDWERX
GPT Image 1 MCP Server
Project Details
- CLOUDWERX-DEV/gpt-image-1-mcp
- MIT License
- Last Updated: 5/13/2025
Recomended MCP Servers
A mcp server that bridges the Model Context Protocol (MCP) with the Agent-to-Agent (A2A) protocol, enabling MCP-compatible AI...
A Model Context Protocol server for interacting with Foundry
challenge 5 activity
PagerDuty MCP Server for LLM Agent Integration
An implementation of Anthropic's Model Context Protocol for the Apache Unomi CDP
Nx Console is the user interface for Nx & Lerna.
MCP server created for Freshdesk, allowing AI models to interact with Freshdesk modules
Terraform Model Context Protocol (MCP) Tool - An experimental CLI tool that enables AI assistants to manage...
Upstash Model Context Server
Featured Templates
View More
