OpenAI GPT-Image MCP Server

![npm version](https://www.npmjs.com/package/openai-gpt-image-mcp-server)
![License: MIT](https://opensource.org/licenses/MIT)
![npm downloads](https://www.npmjs.com/package/openai-gpt-image-mcp-server)

English | 日本語

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

Features

$3

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

$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

$3

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

$3

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

$3

bash

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





$3



Add to your Claude Desktop config file (

~/Library/Application Support/Claude/claude_desktop_config.json

 on macOS):

json

{

  "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



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



$3



In Claude, try:

"Generate a beautiful sunset landscape"





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



---



Installation



$3

bash

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

$3

bash

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



$3



1. Visit OpenAI Platform

2. Log in or create an account

3. 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

4. Create a new API key in the API Keys section

5. Save the key securely



$3



Set your API key as an environment variable:

bash

Linux/macOS

export OPENAI_API_KEY="sk-proj-..."



Windows (PowerShell)

$env:OPENAI_API_KEY="sk-proj-..."





Or create a

.env

 file:

bash

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





$3



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

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.



$3



For Claude Code, use this configuration:



Windows:

json

{

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

json

{

  "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



$3



Generate a beautiful sunset landscape

$3



Generate a 1536x1024 wide mountain landscape

$3



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

$3



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

$3



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

the background to a beautiful beach.

$3



Transform this photo into an oil painting style

$3



Generate an illustration of an apple with a transparent background

$3



Generate 5 different variations of a cyberpunk cityscape

$3



Show me my image generation history from the last week

$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.



$3

bash

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

$3

json

{

  "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

}

$3

bash

openai-gpt-image-batch  [options]



Options:

  --output-dir       Output directory

  --format      Output format (default: text)

  --timeout            Timeout in milliseconds

  --max-concurrent      Max concurrent jobs (1-10)

  --estimate-only          Estimate cost without executing

  --help, -h               Show help

  --version, -v            Show version





$3



- 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



$3



Four example configurations are included:



1. batch-simple.json: Basic batch with 3 images

2. batch-detailed.json: Detailed configuration with custom settings (5 images)

3. batch-multi-variant.json: Multi-variant generation (3-5 variants per prompt)

4. batch-large-scale.json: Large-scale batch processing (10+ images)



$3



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



$3



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



$3



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





$3



List images in a directory.



Parameters:

-

directory

: Path to search (default: current directory)



$3



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



$3



Get detailed information about a specific generation.



Parameters:

-

uuid

 (required): History record UUID



$3



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



$3



Check the status of an async job.



Parameters:

-

job_id (required): Job ID from start_generation_job





$3



Get the result of a completed job.



Parameters:

-

job_id

 (required): Job ID



$3



Cancel a pending or running job.



Parameters:

-

job_id

 (required): Job ID to cancel



$3



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



$3



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



$3



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



$3



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



$3



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:

bash

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:

json

{

  "mcpServers": {

    "openai-gpt-image": {

      "env": {

        "OPENAI_API_KEY": "sk-proj-...",

        "OPENAI_IMAGE_EMBED_METADATA": "false"

      }

    }

  }

}





Change metadata detail level:

json

{

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



$3



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/





$3



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



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

   /tmp/myimage.png → ❌ rejected (outside base)





2. Relative paths: Resolved from base directory



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

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





3. Security: Path traversal attacks prevented



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





4. Auto-creation: Parent directories are created automatically



$3



Set the

OPENAI_IMAGE_OUTPUT_DIR

 environment variable:

json

{

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



$3



- Input directory: Same as output directory by default

- Can be customized with

OPENAI_IMAGE_INPUT_DIR

 environment variable



$3



1. Relative paths: Resolved from input base directory



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

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





2. Absolute paths: Must be within base directory



   ~/Downloads/openai-images/photo.png → ✅ allowed

   /tmp/photo.png → ❌ rejected (outside base)





3. Security: Same sandboxing as output paths

   - Path traversal prevented

   - System files protected

   - Other user files protected



$3

json

{

  "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





$3



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

 |



$3



Enable detailed logging:

bash

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





Security



$3

- 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



$3



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:

json

{

  "mcpServers": {

    "openai-gpt-image": {

      "env": {

        "OPENAI_IMAGE_OUTPUT_DIR": "/path/to/your/output",

        "OPENAI_IMAGE_INPUT_DIR": "/path/to/your/input"

      }

    }

  }

}





Development

bash

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

- Model Context Protocol
- OpenAI API
- Claude Desktop

---

Happy Image Generating! 🎨

OpenAI GPT-Image MCP Server

Features

$3

Prerequisites

Quick Start (5 Minutes)

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

$3

bash

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





$3



Add to your Claude Desktop config file (

~/Library/Application Support/Claude/claude_desktop_config.json

 on macOS):

json

{

  "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



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



$3



In Claude, try:

"Generate a beautiful sunset landscape"





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



---



Installation



$3

bash

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

$3

bash

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



$3



1. Visit OpenAI Platform

2. Log in or create an account

3. 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

4. Create a new API key in the API Keys section

5. Save the key securely



$3



Set your API key as an environment variable:

bash

Linux/macOS

export OPENAI_API_KEY="sk-proj-..."



Windows (PowerShell)

$env:OPENAI_API_KEY="sk-proj-..."





Or create a

.env

 file:

bash

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





$3



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

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.



$3



For Claude Code, use this configuration:



Windows:

json

{

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

json

{

  "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



$3



Generate a beautiful sunset landscape

$3



Generate a 1536x1024 wide mountain landscape

$3



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

$3



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

$3



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

the background to a beautiful beach.

$3



Transform this photo into an oil painting style

$3



Generate an illustration of an apple with a transparent background

$3



Generate 5 different variations of a cyberpunk cityscape

$3



Show me my image generation history from the last week

$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.



$3

bash

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

$3

json

{

  "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

}

$3

bash

openai-gpt-image-batch  [options]



Options:

  --output-dir       Output directory

  --format      Output format (default: text)

  --timeout            Timeout in milliseconds

  --max-concurrent      Max concurrent jobs (1-10)

  --estimate-only          Estimate cost without executing

  --help, -h               Show help

  --version, -v            Show version





$3



- 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



$3



Four example configurations are included:



1. batch-simple.json: Basic batch with 3 images

2. batch-detailed.json: Detailed configuration with custom settings (5 images)

3. batch-multi-variant.json: Multi-variant generation (3-5 variants per prompt)

4. batch-large-scale.json: Large-scale batch processing (10+ images)



$3



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



$3



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



$3



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





$3



List images in a directory.



Parameters:

-

directory

: Path to search (default: current directory)



$3



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



$3



Get detailed information about a specific generation.



Parameters:

-

uuid

 (required): History record UUID



$3



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



$3



Check the status of an async job.



Parameters:

-

job_id (required): Job ID from start_generation_job





$3



Get the result of a completed job.



Parameters:

-

job_id

 (required): Job ID



$3



Cancel a pending or running job.



Parameters:

-

job_id

 (required): Job ID to cancel



$3



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



$3



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



$3



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



$3



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



$3



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:

bash

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:

json

{

  "mcpServers": {

    "openai-gpt-image": {

      "env": {

        "OPENAI_API_KEY": "sk-proj-...",

        "OPENAI_IMAGE_EMBED_METADATA": "false"

      }

    }

  }

}





Change metadata detail level:

json

{

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



$3



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/





$3



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



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

   /tmp/myimage.png → ❌ rejected (outside base)





2. Relative paths: Resolved from base directory



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

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





3. Security: Path traversal attacks prevented



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





4. Auto-creation: Parent directories are created automatically



$3



Set the

OPENAI_IMAGE_OUTPUT_DIR

 environment variable:

json

{

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



$3



- Input directory: Same as output directory by default

- Can be customized with

OPENAI_IMAGE_INPUT_DIR

 environment variable



$3



1. Relative paths: Resolved from input base directory



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

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





2. Absolute paths: Must be within base directory



   ~/Downloads/openai-images/photo.png → ✅ allowed

   /tmp/photo.png → ❌ rejected (outside base)





3. Security: Same sandboxing as output paths

   - Path traversal prevented

   - System files protected

   - Other user files protected



$3

json

{

  "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





$3



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

 |



$3



Enable detailed logging:

bash

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





Security



$3

- 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



$3



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:

json

{

  "mcpServers": {

    "openai-gpt-image": {

      "env": {

        "OPENAI_IMAGE_OUTPUT_DIR": "/path/to/your/output",

        "OPENAI_IMAGE_INPUT_DIR": "/path/to/your/input"

      }

    }

  }

}





Development

bash

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

- Model Context Protocol
- OpenAI API
- Claude Desktop

---

Happy Image Generating! 🎨