gpt-image-1-mcp

Quick Start

npx -y @cloudwerxlab/gpt-image-1-mcp

Prerequisites

Environment Variables

Example Usage with NPX

# 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

# 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

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

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

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

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:

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

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

Acknowledgments