@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.
```bash
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 |
```bash
# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-openai-api-key
# Optional: Set custom output directory
export GPT_IMAGE_OUTPUT_DIR=/home/username/Pictures/ai-generated-images
# Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp
```
|
| Windows (PowerShell) |
```powershell
# Set your OpenAI API key
$env:OPENAI_API_KEY = "sk-your-openai-api-key"
# Optional: Set custom output directory
$env:GPT_IMAGE_OUTPUT_DIR = "C:\Users\username\Pictures\ai-generated-images"
# Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp
```
|
| Windows (Command Prompt) |
```cmd
:: Set your OpenAI API key
set OPENAI_API_KEY=sk-your-openai-api-key
:: Optional: Set custom output directory
set GPT_IMAGE_OUTPUT_DIR=C:\Users\username\Pictures\ai-generated-images
:: Run the server with NPX
npx -y @cloudwerxlab/gpt-image-1-mcp
```
|
## 🔌 Integration with MCP Clients
### 🛠️ Setting Up in an MCP Client
Step 1: Locate Settings File
- For Roo:
c:\Users\<username>\AppData\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
- For VS Code MCP Extension: Check your extension documentation for the settings file location
- For Cursor:
~/.config/cursor/mcp_settings.json (Linux/macOS) or %APPDATA%\Cursor\mcp_settings.json (Windows)
- For Augment:
~/.config/augment/mcp_settings.json (Linux/macOS) or %APPDATA%\Augment\mcp_settings.json (Windows)
- For Windsurf:
~/.config/windsurf/mcp_settings.json (Linux/macOS) or %APPDATA%\Windsurf\mcp_settings.json (Windows)
|
Step 2: Add Configuration
Add the following configuration to the mcpServers object:
|
```json
{
"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 |
```json
{
"mcpServers": {
"gpt-image-1": {
"command": "npx",
"args": ["-y", "@cloudwerxlab/gpt-image-1-mcp"],
"env": {
"OPENAI_API_KEY": "sk-your-openai-api-key",
"GPT_IMAGE_OUTPUT_DIR": "C:\\Users\\username\\Pictures\\ai-generated-images"
}
}
}
}
```
|
| Linux/macOS |
```json
{
"mcpServers": {
"gpt-image-1": {
"command": "npx",
"args": ["-y", "@cloudwerxlab/gpt-image-1-mcp"],
"env": {
"OPENAI_API_KEY": "sk-your-openai-api-key",
"GPT_IMAGE_OUTPUT_DIR": "/home/username/Pictures/ai-generated-images"
}
}
}
}
```
|
> **Note**: For Windows paths, use double backslashes (`\\`) to escape the backslash character in JSON. For Linux/macOS, use forward slashes (`/`).
## ✨ Features
🎨 Core Tools
create_image: Generate new images from text promptscreate_image_edit: Edit existing images with text prompts and masks
|
🚀 Key Benefits
- Simple integration with MCP clients
- Full access to OpenAI's gpt-image-1 capabilities
- Streamlined workflow for AI image generation
|
### 💡 Enhanced Capabilities
📊 Output & Formatting
- ✅ Beautifully Formatted Output: Responses include emojis and detailed information
- ✅ Automatic Image Saving: All generated images saved to disk for easy access
- ✅ Detailed Token Usage: View token consumption for each request
|
⚙️ Configuration & Handling
- ✅ Configurable Output Directory: Customize where images are saved
- ✅ File Path Support: Edit images using file paths instead of base64 encoding
- ✅ Comprehensive Error Handling: Detailed error reporting with specific error codes, descriptions, and troubleshooting suggestions
|
## 🔄 How It Works
| 🖼️ Image Generation |
✏️ Image Editing |
- Server receives prompt and parameters
- Calls OpenAI API using gpt-image-1 model
- API returns base64-encoded images
- Server saves images to configured directory
- Returns formatted response with paths and metadata
|
- Server receives image, prompt, and optional mask
- For file paths, reads and prepares files for API
- Uses direct curl command for proper MIME handling
- API returns base64-encoded edited images
- Server saves images to configured directory
- Returns formatted response with paths and metadata
|
### 📁 Output Directory Behavior
📂 Storage Location
- 🔹 Default Location: User's Pictures folder under
gpt-image-1 subfolder (e.g., C:\Users\username\Pictures\gpt-image-1 on Windows)
- 🔹 Custom Location: Set via
GPT_IMAGE_OUTPUT_DIR environment variable
- 🔹 Fallback Location:
./generated-images (if Pictures folder can't be determined)
|
🗂️ File Management
- 🔹 Directory Creation: Automatically creates output directory if it doesn't exist
- 🔹 File Naming: Images saved with timestamped filenames (e.g.,
image-2023-05-05T12-34-56-789Z.png)
- 🔹 Cross-Platform: Works on Windows, macOS, and Linux with appropriate Pictures folder detection
|
## Installation & Usage
### NPM Package
This package is available on npm: [@cloudwerxlab/gpt-image-1-mcp](https://www.npmjs.com/package/@cloudwerxlab/gpt-image-1-mcp)
You can install it globally:
```bash
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
```xml
gpt-image-1
create_image
{
"prompt": "A futuristic city skyline at sunset, digital art",
"size": "1024x1024",
"quality": "high",
"n": 1,
"background": "auto"
}
```
#### 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
```xml
gpt-image-1
create_image_edit
{
"image": "BASE64_ENCODED_IMAGE_STRING",
"prompt": "Add a small robot in the corner",
"mask": "BASE64_ENCODED_MASK_STRING",
"quality": "high"
}
```
#### Example with File Path
```xml
gpt-image-1
create_image_edit
{
"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"
}
```
#### 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 |
🖼️ MIME Type Errors
Errors related to image format or MIME type handling
|
Ensure image files have the correct extension (.png, .jpg, etc.) that matches their actual format. The server uses file extensions to determine MIME types.
|
🔑 API Key Issues
Authentication errors with OpenAI API
|
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.
|
🛠️ Build Errors
Issues when building from source
|
Ensure you have the correct TypeScript version installed (v5.3.3 or compatible) and that your tsconfig.json is properly configured. Run npm install to ensure all dependencies are installed.
|
📁 Output Directory Issues
Problems with saving generated images
|
Check if the process has write permissions to the configured output directory. Try using an absolute path for GPT_IMAGE_OUTPUT_DIR if relative paths aren't working.
|
### 🔍 Error Handling and Reporting
The MCP server includes comprehensive error handling that provides detailed information when something goes wrong. When an error occurs:
1. **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
2. **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
