Gpt Image 1 MCP

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

🔑 Environment Variables

💻 Usage Examples

Basic Usage

# 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

Advanced Usage (Windows - 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

Advanced Usage (Windows - Command Prompt)

:: 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:

{
  "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

{
  "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 |

{
  "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"
      }
    }
  }
}

⚠️ Important 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

• ✅ 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

📁 Output Directory Behavior

📦 Installation

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

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

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

🔍 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

• OpenAI for providing the gpt-image-1 model
• Model Context Protocol for the protocol specification

Report Bug • Request Feature • Visit Our Website

Developed with ❤️ by CLOUDWERX