Skip to main content
Glama
Sign In
deenesjakoruzh
GPT Image 1 MCP

GPT Image 1 MCP

by CLOUDWERX-DEV
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

🚀 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

Related MCP server: OpenAI 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

Available Tools

2 tools
create_imageD

Inputs: prompt (required), background, n, output_compression, +5 more.

create_image_editD

Inputs: image (required), prompt (required), background, mask, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    D1.5/5.0

    Scored across 2 tools

    Disambiguation2/5

    The two tools have overlapping purposes—both involve creating images—and without descriptions, it's unclear how they differ. 'create_image_edit' suggests editing an existing image, but this could easily be confused with the base 'create_image' tool, leading to potential misselection.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern with 'create_image' as the base, and 'create_image_edit' extends this logically. The naming is predictable and clear, with no deviations in style or convention.

    Tool Count2/5

    With only 2 tools, the server feels thin for an image-related domain, which typically requires operations like listing, retrieving, updating, or deleting images. This limited set may not support common workflows, making it under-scoped.

    Completeness1/5

    The tool surface is severely incomplete for an image server; there are no tools for reading, updating, deleting, or managing images beyond creation and editing. This will cause significant agent failures in handling image lifecycles or varied tasks.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches