🚀 Quick Start

npx -y @ramarivera/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 @ramarivera/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 @ramarivera/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 @ramarivera/gpt-image-1-mcp

🔌 Integration with MCP Clients

🛠️ Setting Up in an MCP Client

Add the following configuration to your MCP client's settings:

{
  "mcpServers": {
    "gpt-image-1": {
      "command": "npx",
      "args": ["-y", "@ramarivera/gpt-image-1-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

⚠️ Claude Desktop Compatibility

📊 Response Size Limitation

Claude Desktop has a ~1MB response size limit. Since gpt-image-1 generates minimum 1024x1024 images, base64-encoded responses will almost always exceed this limit and cause failures.

✅ Recommended Solution

Always use responseFormat: "paths" when using this MCP server with Claude Desktop.

This setting returns only the file paths where images are saved, instead of the base64-encoded image data. Images are always saved to disk regardless of this setting—the parameter only controls what's returned in the response payload.

📝 Example Usage with Claude Desktop

<use_mcp_tool>
<server_name>gpt-image-1</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
  "prompt": "A beautiful sunset over mountains",
  "responseFormat": "paths"
}
</arguments>
</use_mcp_tool>

🔄 Response Format Options

| Value | Description | Use Case | |-------|-------------|----------| | "paths" | Returns only file paths | Recommended for Claude Desktop | | "base64" | Returns only base64-encoded image data | When you need the raw image data and response size isn't limited | | "base64,paths" | Returns both (default) | For backward compatibility; may fail on Claude Desktop |

✨ Features

💡 Enhanced Capabilities

📖 API Reference

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) | | moderation | string | No | Moderation level: "low" or "auto" (default) | | responseFormat | string | No | Response data: "paths" (recommended for Claude Desktop), "base64", or "base64,paths" (default) |

Example

{
  "prompt": "A futuristic city skyline at sunset, digital art",
  "size": "1024x1024",
  "quality": "high",
  "responseFormat": "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) | | responseFormat | string | No | Response data: "paths" (recommended for Claude Desktop), "base64", or "base64,paths" (default) |

Example with File Path

{
  "image": {
    "filePath": "/path/to/your/image.png"
  },
  "prompt": "Add a small robot in the corner",
  "responseFormat": "paths"
}

📁 Output Directory Behavior

🔧 Troubleshooting

🚨 Common Issues

| Issue | Solution | |-------|----------| | Response too large | Use responseFormat: "paths" instead of default | | MIME Type Errors | Ensure image files have correct extensions (.png, .jpg) | | API Key Issues | Verify your OpenAI API key has access to gpt-image-1 | | Output Directory Issues | Check write permissions or use absolute path for GPT_IMAGE_OUTPUT_DIR |

📄 License

🙏 Acknowledgments