https://github.com/cloudwerx-dev/gpt-image-1-mcp

A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.
https://github.com/cloudwerx-dev/gpt-image-1-mcp

generation gpt-image-1 image mcp mcp-server openai

Last synced: 2 months ago
JSON representation

A Model Context Protocol (MCP) server for generating and editing images using the OpenAI gpt-image-1 model.

Host: GitHub
URL: https://github.com/cloudwerx-dev/gpt-image-1-mcp
Owner: CLOUDWERX-DEV
License: mit
Created: 2025-05-07T05:32:30.000Z (5 months ago)
Default Branch: main
Last Pushed: 2025-05-07T06:43:03.000Z (5 months ago)
Last Synced: 2025-06-17T13:20:03.579Z (4 months ago)
Topics: generation, gpt-image-1, image, mcp, mcp-server, openai
Language: JavaScript
Homepage: http://cloudwerx.dev
Size: 2.98 MB
Stars: 10
Watchers: 1
Forks: 4
Open Issues: 4
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

@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 prompts

create_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

For providing the gpt-image-1 model

For the protocol specification

Report Bug •
Request Feature •
Visit Our Website

Developed with ❤️ by CLOUDWERX

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/cloudwerx-dev/gpt-image-1-mcp

Awesome Lists containing this project

README

@cloudwerxlab/gpt-image-1-mcp

Step 1: Locate Settings File

Step 2: Add Configuration

🎨 Core Tools

🚀 Key Benefits

📊 Output & Formatting

⚙️ Configuration & Handling

📂 Storage Location

🗂️ File Management

🖼️ MIME Type Errors

🔑 API Key Issues

🛠️ Build Errors

📁 Output Directory Issues