OpenAI GPT-Image MCP Server

A Model Context Protocol (MCP) server that enables image generation and editing using OpenAI's GPT Image API (gpt-image-1, gpt-image-1.5, and gpt-image-2). Works seamlessly with Claude Desktop, Claude Code, and other MCP-compatible clients.

Features

Core Capabilities

🎨 High-Quality Image Generation: State-of-the-art text-to-image generation
📝 Excellent Text Rendering: Accurate text rendering within images
✂️ Precise Image Editing: Inpainting for targeted modifications
🔄 Image Transformation: Style transfer and reinterpretation
📐 Flexible Sizing: Square, portrait, and landscape formats
🎚️ Quality Control: Choose from low, medium, or high quality
🖼️ Multiple Formats: PNG, JPEG, and WebP support
🌐 Cross-Platform: Works on macOS, Windows, and Linux with smart path handling

Advanced Features (v1.0.3+)

🎲 Multi-Image Generation: Generate 1-10 images in a single request
📚 History Management: SQLite-based generation history with search
⚡ Async Job System: Background processing with progress tracking
🏷️ Metadata Embedding: Automatic metadata in PNG/JPEG files
💰 Cost Management: Automatic token usage and cost estimation
🛡️ Content Filtering: Built-in safety filters
📁 Image Management: List and organize generated images
🔧 Debug Mode: Detailed logging for troubleshooting

GPT-Image-1.5 Support (v1.2.0+)

🚀 gpt-image-1.5 Model: 4x faster generation, 20% lower cost
📝 Better Text Rendering: Improved accuracy for text in images
👤 Input Fidelity: High-fidelity face/logo preservation (edit & transform)
🔧 Model Selection: Choose between gpt-image-1 and gpt-image-1.5

GPT-Image-2 Support (v1.3.0+)

🆕 gpt-image-2 Model: Latest OpenAI image model with flexible sizing
📐 Flexible Sizes: 2K/4K presets (2048x2048, 2048x1152, 3840x2160, etc.) and custom WxH (16px multiples, each edge ≤3840, ratio ≤3:1, 0.65–8.3 megapixels)
🧪 Experimental 4K: 3840x2160 / 2160x3840 available (quality/stability not guaranteed by OpenAI)
🎯 Auto High-Fidelity: Reference images are always processed at high fidelity — input_fidelity is ignored
⚠️ No Transparent Background: transparent_background is not supported; use gpt-image-1 / 1.5 if you need transparency
💵 Lower Low-Tier Pricing: low quality 1024x1024 is ~$0.006/image

Batch Processing (v1.1.0+)

📦 CLI Batch Tool: Generate multiple images at once via command line
🔄 Concurrency Control: Parallel processing with configurable limits
📊 Cost Estimation: Preview costs before execution
⚙️ Retry Policy: Automatic retry for failed jobs
📝 Multiple Output Formats: Text or JSON results
🤖 GitHub Actions: Automated batch generation from Issue comments
💾 Batch History: Track and manage batch executions

Prerequisites

Node.js v18 or higher
OpenAI API Key with verified organization
MCP-compatible client (Claude Desktop, Claude Code, etc.)

⚠️ Important: Using gpt-image-1 requires OpenAI Organization Verification.

Quick Start (5 Minutes)

Prerequisites: Node.js 18+, OpenAI API key with verified organization

1. Install

npm install -g openai-gpt-image-mcp-server

2. Configure

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openai-gpt-image": {
      "command": "openai-gpt-image-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-key-here"
      }
    }
  }
}

Windows users: Use openai-gpt-image-mcp-server.cmd as the command.

3. Restart Claude Desktop

Completely restart Claude Desktop (quit from system tray/menu bar).

4. Test

In Claude, try: "Generate a beautiful sunset landscape"

Done! For detailed setup and advanced features, see Full Installation Guide below.

Installation

Quick Install

npm install -g openai-gpt-image-mcp-server

From Source

git clone https://github.com/ex-takashima/openAI-gpt-image-1-MCP-SERVER.git
cd openAI-gpt-image-1-MCP-SERVER
npm install
npm run build

Setup

1. Get Your OpenAI API Key

Visit OpenAI Platform
Log in or create an account
Complete Organization Verification:
- Go to Settings > Organization > General
- Click "Verify Organization"
- Upload government-issued ID
- Complete facial verification
- Wait up to 15 minutes for approval
Create a new API key in the API Keys section
Save the key securely

2. Configure API Key

Set your API key as an environment variable:

# Linux/macOS
export OPENAI_API_KEY="sk-proj-..."

# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-proj-..."

Or create a .env file:

OPENAI_API_KEY=sk-proj-your-api-key-here

3. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openai-gpt-image": {
      "command": "openai-gpt-image-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-api-key-here",
        "OPENAI_IMAGE_OUTPUT_DIR": "/Users/username/Pictures/ai-images"
      }
    }
  }
}

Windows users: Use openai-gpt-image-mcp-server.cmd as the command.

Optional Environment Variables:

OPENAI_IMAGE_OUTPUT_DIR: Custom output directory (default: ~/Downloads/openai-images)
OPENAI_IMAGE_INPUT_DIR: Custom input directory (default: same as output directory)
OPENAI_IMAGE_EMBED_METADATA: Enable metadata embedding (true/false, default: true)
OPENAI_IMAGE_METADATA_LEVEL: Metadata detail level (minimal/standard/full, default: standard)
OPENAI_IMAGE_THUMBNAIL: Enable thumbnail generation (true/false, default: false)
OPENAI_IMAGE_THUMBNAIL_SIZE: Thumbnail size in pixels (default: 128, range: 1-512)
OPENAI_IMAGE_THUMBNAIL_QUALITY: Thumbnail JPEG quality (default: 60, range: 1-100)
OPENAI_ORGANIZATION: OpenAI organization ID (if you belong to multiple)
HISTORY_DB_PATH: Custom database location (default: ~/.openai-gpt-image/history.db)
DEBUG: Set to 1 for detailed logging

📖 Complete reference: See Environment Variables Reference for detailed documentation of all variables.

Restart Claude Desktop after saving.

4. Configure Claude Code

For Claude Code, use this configuration:

Windows:

{
  "mcpServers": {
    "openai-gpt-image": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "openai-gpt-image-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-api-key-here"
      }
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "openai-gpt-image": {
      "command": "npx",
      "args": ["-y", "openai-gpt-image-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-api-key-here"
      }
    }
  }
}

Usage Examples

Basic Image Generation

Generate a beautiful sunset landscape

With Size Specification

Generate a 1536x1024 wide mountain landscape

With Quality

Generate a high-quality image of an astronaut floating in space

Text Rendering

Create an image with "WELCOME" written on a large sign

Image Editing

Edit this photo's background. Use the mask image to change only
the background to a beautiful beach.

Image Transformation

Transform this photo into an oil painting style

Transparent Background

Generate an illustration of an apple with a transparent background

Multi-Image Generation (v1.0.3+)

Generate 5 different variations of a cyberpunk cityscape

View History (v1.0.3+)

Show me my image generation history from the last week

Async Jobs (v1.0.3+)

Start a background job to generate 10 high-quality landscape images.
I want to continue working while it processes.

Batch Processing

Generate multiple images at once using the CLI batch tool.

Quick Start

# Basic batch generation
openai-gpt-image-batch examples/batch-simple.json

# Estimate cost before execution
openai-gpt-image-batch examples/batch-detailed.json --estimate-only

# JSON output format
openai-gpt-image-batch examples/batch-large-scale.json --format json > result.json

Batch Configuration Example

{
  "jobs": [
    {
      "prompt": "A beautiful sunset over the ocean",
      "output_path": "sunset.png",
      "size": "1536x1024",
      "quality": "high"
    },
    {
      "prompt": "A futuristic city skyline",
      "output_path": "city.png",
      "quality": "medium"
    }
  ],
  "max_concurrent": 3,
  "timeout": 900000
}

CLI Options

openai-gpt-image-batch <config.json> [options]

Options:
  --output-dir <path>      Output directory
  --format <text|json>     Output format (default: text)
  --timeout <ms>           Timeout in milliseconds
  --max-concurrent <n>     Max concurrent jobs (1-10)
  --estimate-only          Estimate cost without executing
  --help, -h               Show help
  --version, -v            Show version

Features

Concurrency Control: Parallel processing with configurable limits (1-10 concurrent jobs)
Cost Estimation: Preview costs before execution with --estimate-only
Retry Policy: Automatic retry for failed jobs (configurable)
Multiple Output Formats: Results in text or JSON format
Timeout Management: Prevent long-running executions
Error Handling: Continue processing even if individual jobs fail
GitHub Actions Integration: Automated batch generation from Issue comments

Sample Configurations

Four example configurations are included:

batch-simple.json: Basic batch with 3 images
batch-detailed.json: Detailed configuration with custom settings (5 images)
batch-multi-variant.json: Multi-variant generation (3-5 variants per prompt)
batch-large-scale.json: Large-scale batch processing (10+ images)

Documentation

For detailed documentation, see:

docs/BATCH_PROCESSING.md - English
docs/BATCH_PROCESSING.ja.md - 日本語

Documentation includes:

Comprehensive CLI usage guide
Batch configuration JSON format
GitHub Actions integration
Troubleshooting guide
Best practices

Available Tools

1. `generate_image`

Generate new images from text prompts.

Parameters:

prompt (required): Image description
output_path: Save location (default: generated_image.png)
size: 1024x1024, 1024x1536, 1536x1024, or auto
quality: low, medium, high, or auto
output_format: png, jpeg, or webp
transparent_background: Enable transparency (PNG only)
moderation: Content filtering level
sample_count: Number of images to generate (1-10, default: 1)
return_base64: Return base64-encoded image

2. `edit_image`

Edit images using inpainting.

Parameters:

prompt (required): Edit description
reference_image_base64 or reference_image_path: Source image
mask_image_base64 or mask_image_path: Mask (transparent = edit area)
output_path: Save location
sample_count: Number of images to generate (1-10, default: 1)
Other parameters same as generate_image

3. `transform_image`

Transform images to new styles.

Parameters:

prompt (required): Transformation description
reference_image_base64 or reference_image_path: Source image
output_path: Save location
sample_count: Number of images to generate (1-10, default: 1)
Other parameters same as generate_image

4. `list_generated_images`

List images in a directory.

Parameters:

directory: Path to search (default: current directory)

5. `list_history`

Browse generation history with optional filters.

Parameters:

limit: Max records (1-100, default: 20)
offset: Skip N records (pagination)
tool_name: Filter by tool (generate_image, edit_image, transform_image)
query: Search in prompts

6. `get_history_by_uuid`

Get detailed information about a specific generation.

Parameters:

uuid (required): History record UUID

7. `start_generation_job`

Start an async image generation job in the background.

Parameters:

tool_name (required): Which tool to use
prompt (required): Generation prompt
Other parameters same as the respective tool

8. `check_job_status`

Check the status of an async job.

Parameters:

job_id (required): Job ID from start_generation_job

9. `get_job_result`

Get the result of a completed job.

Parameters:

job_id (required): Job ID

10. `cancel_job`

Cancel a pending or running job.

Parameters:

job_id (required): Job ID to cancel

11. `list_jobs`

List async jobs with optional filters.

Parameters:

status: Filter by status (pending, running, completed, failed, cancelled)
tool_name: Filter by tool
limit: Max results (1-100, default: 20)
offset: Skip N results

Advanced Features

Multi-Image Generation

All generation tools support the sample_count parameter to generate multiple images at once:

Generate 5 variations of a cat playing with yarn

Supported range: 1-10 images per request
Files are automatically numbered: output_1.png, output_2.png, etc.
Cost is multiplied by the number of images
All files are recorded in history

History Management

Every generation is automatically saved to a local SQLite database (~/.openai-gpt-image/history.db):

View recent history:

Show me the last 10 images I generated

Search history:

Find all images I generated with "sunset" in the prompt

Get details:

Show me the details for this history ID: 8796265a-8dc8-48f4-9b40-fe241985379b

The history includes:

Generation timestamp
Tool used
Prompt and parameters
Output file paths
Cost information

Async Job System

For long-running operations or batch processing, use async jobs:

Start a background job:

Start a background job to generate 10 high-quality space images

Check status:

Check the status of job b7912655-0d8e-4ecc-be58-cbc2c4746932

Get results:

Get the results for job b7912655-0d8e-4ecc-be58-cbc2c4746932

Job statuses:

⏳ pending: Waiting to start
🔄 running: Currently processing
✅ completed: Finished successfully
❌ failed: Error occurred
🚫 cancelled: Manually cancelled

Metadata Embedding

Generated images automatically include embedded metadata:

PNG files: tEXt chunks with:

openai_gpt_image_uuid: Unique identifier
params_hash: SHA-256 hash of parameters
tool_name: Tool used (generate_image, edit_image, transform_image)
model: Model name (gpt-image-1)
created_at: ISO 8601 timestamp
size: Image dimensions (e.g., "1024x1024")
quality: Quality level (low, medium, high)
prompt: Generation prompt (full level only)
parameters: Complete generation parameters (full level only)

JPEG/WebP files: EXIF ImageDescription with JSON metadata

View metadata:

# macOS/Linux
exiftool generated_image.png | grep openai

# Windows (PowerShell)
exiftool generated_image.png

This allows you to identify how an image was created even after moving it to different locations.

Controlling Metadata Embedding

You can control metadata embedding behavior using environment variables:

Disable metadata embedding entirely:

{
  "mcpServers": {
    "openai-gpt-image": {
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_IMAGE_EMBED_METADATA": "false"
      }
    }
  }
}

Change metadata detail level:

{
  "mcpServers": {
    "openai-gpt-image": {
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_IMAGE_METADATA_LEVEL": "minimal"
      }
    }
  }
}

Metadata levels:

minimal: UUID and parameter hash only
- Best for: Privacy-focused use cases
- Size impact: Minimal (~100 bytes)
- Contains: openai_gpt_image_uuid, params_hash
standard (default): Basic generation information
- Best for: Most use cases, balances detail and privacy
- Size impact: Small (~300 bytes)
- Contains: All minimal fields + tool_name, model, created_at, size, quality
full: Complete generation details
- Best for: Full traceability and reproducibility
- Size impact: Medium (varies by prompt length, typically 500-2000 bytes)
- Contains: All standard fields + prompt, parameters

Note: Metadata embedding is "best effort" - if embedding fails, the image is still saved without metadata. Enable DEBUG=1 to see metadata embedding details.

Output Path Handling

Images are saved with smart cross-platform path handling:

Default Behavior

By default, all images are saved to ~/Downloads/openai-images:

macOS: /Users/username/Downloads/openai-images/
Windows: C:\Users\username\Downloads\openai-images\
Linux: /home/username/Downloads/openai-images/

Path Resolution Priority

Absolute paths: Must be within base directory (security sandboxing)

~/Downloads/openai-images/myimage.png → ✅ saved (within base)
/tmp/myimage.png → ❌ rejected (outside base)

Relative paths: Resolved from base directory

myimage.png → ~/Downloads/openai-images/myimage.png
subfolder/image.png → ~/Downloads/openai-images/subfolder/image.png

Security: Path traversal attacks prevented

../other/image.png → ❌ rejected (path traversal)

Auto-creation: Parent directories are created automatically

Custom Output Directory

Set the OPENAI_IMAGE_OUTPUT_DIR environment variable:

{
  "mcpServers": {
    "openai-gpt-image": {
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_IMAGE_OUTPUT_DIR": "/Users/username/Pictures/ai-images"
      }
    }
  }
}

Now myimage.png will be saved to /Users/username/Pictures/ai-images/myimage.png.

Input Path Handling

Input images (for edit_image and transform_image) are also managed with security:

Default Behavior

Input directory: Same as output directory by default
Can be customized with OPENAI_IMAGE_INPUT_DIR environment variable

Path Resolution

Relative paths: Resolved from input base directory

photo.png → ~/Downloads/openai-images/photo.png
source/photo.png → ~/Downloads/openai-images/source/photo.png

Absolute paths: Must be within base directory

~/Downloads/openai-images/photo.png → ✅ allowed
/tmp/photo.png → ❌ rejected (outside base)

Security: Same sandboxing as output paths
- Path traversal prevented
- System files protected
- Other user files protected

Separate Input/Output Directories

{
  "mcpServers": {
    "openai-gpt-image": {
      "env": {
        "OPENAI_API_KEY": "sk-proj-...",
        "OPENAI_IMAGE_INPUT_DIR": "~/Pictures/source-images",
        "OPENAI_IMAGE_OUTPUT_DIR": "~/Pictures/generated-images"
      }
    }
  }
}

Cost Management

All operations automatically report:

Input/output token counts
Estimated cost in USD
Cost breakdown (text processing + image generation)
Parameter details

Example output:

📊 Usage Statistics

- Input tokens: 15
- Output tokens (image): 4,096
- Total tokens: 4,111
- Estimated cost: $0.042

💰 Cost breakdown:
  - Text processing: $0.000150
  - Image generation: $0.041850

📏 Parameters: high quality | 1024x1024 | png

Pricing Examples

The following costs are approximate estimates. Actual pricing may vary.

Size	Quality	Approx. Cost
1024x1024	low	$0.01-0.02
1024x1024	medium	$0.04-0.07
1024x1024	high	$0.17-0.19

Important: See OpenAI Pricing for current official rates.

Troubleshooting

Issue	Solution
Server won't start	Verify Node.js v18+, check PATH
Authentication error	Check `OPENAI_API_KEY`
"organization must be verified"	Complete verification at OpenAI Platform
Generation fails	Try `moderation: "low"` or refine prompt
Edit doesn't work	Ensure mask is transparent PNG
File access error (macOS/Windows)	Use absolute paths or set `OPENAI_IMAGE_OUTPUT_DIR`
"ENOENT: no such file or directory"	Check path format, try default `~/Downloads/openai-images`

Debug Mode

Enable detailed logging:

DEBUG=1 openai-gpt-image-mcp-server

Security

API Key Security

Never commit API keys to version control
Use environment variables or .env files
Set file permissions: chmod 600 .env
Rotate keys regularly
Monitor usage at OpenAI Dashboard

File Access Sandboxing

All file operations (read/write) are restricted to configured base directories:

Protected system files:

Unix/Linux/macOS: /etc/*, /var/*, /home/other_user/*, /root/*
Windows: C:\Windows\*, C:\Program Files\*, C:\Users\OtherUser\*

Security features:

✅ Path traversal attack prevention (../ restrictions)
✅ System file protection
✅ Other user data protection
✅ Operations limited to configured directories only

To access different directories, configure base directories:

{
  "mcpServers": {
    "openai-gpt-image": {
      "env": {
        "OPENAI_IMAGE_OUTPUT_DIR": "/path/to/your/output",
        "OPENAI_IMAGE_INPUT_DIR": "/path/to/your/input"
      }
    }
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run locally
npm start

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.

Acknowledgments

Happy Image Generating! 🎨

Name		Name	Last commit message	Last commit date
.claude/agents		.claude/agents
.github/workflows		.github/workflows
docs		docs
examples		examples
src		src
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
package.json		package.json
test-cross-platform.js		test-cross-platform.js
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

OpenAI GPT-Image MCP Server

Features

Core Capabilities

Advanced Features (v1.0.3+)

GPT-Image-1.5 Support (v1.2.0+)

GPT-Image-2 Support (v1.3.0+)

Batch Processing (v1.1.0+)

Prerequisites

Quick Start (5 Minutes)

1. Install

2. Configure

3. Restart Claude Desktop

4. Test

Installation

Quick Install

From Source

Setup

1. Get Your OpenAI API Key

2. Configure API Key

3. Configure Claude Desktop

4. Configure Claude Code

Usage Examples

Basic Image Generation

With Size Specification

With Quality

Text Rendering

Image Editing

Image Transformation

Transparent Background

Multi-Image Generation (v1.0.3+)

View History (v1.0.3+)

Async Jobs (v1.0.3+)

Batch Processing

Quick Start

Batch Configuration Example

CLI Options

Features

Sample Configurations

Documentation

Available Tools

1. generate_image

2. edit_image

3. transform_image

4. list_generated_images

5. list_history

6. get_history_by_uuid

7. start_generation_job

8. check_job_status

9. get_job_result

10. cancel_job

11. list_jobs

Advanced Features

Multi-Image Generation

History Management

Async Job System

Metadata Embedding

Controlling Metadata Embedding

Output Path Handling

Default Behavior

Path Resolution Priority

Custom Output Directory

Input Path Handling

Default Behavior

Path Resolution

Separate Input/Output Directories

Cost Management

Pricing Examples

Troubleshooting

Debug Mode

Security

API Key Security

File Access Sandboxing

Development

Contributing

License

Acknowledgments

1. `generate_image`

2. `edit_image`

3. `transform_image`

4. `list_generated_images`

5. `list_history`

6. `get_history_by_uuid`

7. `start_generation_job`

8. `check_job_status`

9. `get_job_result`

10. `cancel_job`

11. `list_jobs`