Which integrations are available for this server?

Offers integration with OpenAI's GPT Image API for generating, editing, and transforming images using models like gpt-image-1, gpt-image-1.5, and gpt-image-2. Supports text-to-image generation, inpainting, style transfer, flexible sizing, quality control, and batch processing.

How do I use OpenAI GPT-Image MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenAI GPT-Image MCP Server generate a realistic portrait of a woman with blue eyes" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OpenAI GPT-Image MCP Server

by ex-takashima

Overview Schema Related Servers Score Discussions

TypeScript

Local

OpenAI GPT-Image MCP Server

npm version License: MIT npm downloads

English | 日本語

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

Related MCP server: openai-imagegen-mcp

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

Available Tools

12 tools

cancel_jobA

Cancel a pending or running async job. Cannot cancel already completed, failed, or cancelled jobs.

ParametersJSON Schema

Name	Required	Description	Default
`job_id`	Yes	Job ID to cancel

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool cancels a job and the applicable states. Without any annotations, the description carries the full burden, but it lacks details on side effects, permissions needed, or irreversibility of the cancellation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences convey the essential information with no unnecessary words. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description adequately covers purpose and constraints. Could mention that cancellation is irreversible or requires specific permissions, but it is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'job_id' is fully described in the input schema ('Job ID to cancel'), and the description adds no additional meaning. With 100% schema coverage, baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Cancel' and the resource 'pending or running async job'. Distinguishes from sibling tools like check_job_status (status check) and list_jobs (listing). Also specifies a constraint on job states.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states that the tool cannot cancel already completed, failed, or cancelled jobs, giving clear context on when not to use it. However, it does not suggest checking job status via sibling tools like check_job_status before calling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_job_statusA

Check the status of an async job. Shows current status (pending/running/completed/failed/cancelled) and progress percentage.

ParametersJSON Schema

Name	Required	Description	Default
`job_id`	Yes	Job ID returned from start_generation_job

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses it's a read-only status check with status and progress, but no additional behavioral context (auth, rate limits).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose and key details. No extra words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple polling tool with one parameter and return described (statuses and progress), the description is complete. Siblings are numerous but tool purpose is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter job_id has 100% schema coverage. Description adds value by specifying it's the ID returned from start_generation_job, clarifying origin.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks async job status, lists possible statuses, and mentions progress percentage. It distinguishes from siblings like list_jobs and get_job_result.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use after start_generation_job (via parameter description), but lacks explicit when-to-use or when-not-use guidance relative to alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_imageA

Edit an existing image using inpainting with OpenAI GPT image models. Requires a reference image and optional mask image (transparent areas are edited). gpt-image-1.5 supports input_fidelity for better face/logo preservation.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	Description of the desired edits
`reference_image_base64`	No	Base64 encoded reference image
`reference_image_path`	No	Path to reference image file
`mask_image_base64`	No	Base64 encoded mask image (transparent areas will be edited)
`mask_image_path`	No	Path to mask image file (transparent areas will be edited)
`output_path`	No	Output file path (default: edited_image.png)
`model`	No	Model to use. gpt-image-2: latest, flexible sizes, input_fidelity is auto-high (field ignored). gpt-image-1.5: supports input_fidelity. gpt-image-1: original. (default: gpt-image-1)
`size`	No	Image size. gpt-image-1/1.5 only support 1024x1024, 1024x1536, 1536x1024, auto. gpt-image-2 also supports 2K/4K presets plus custom WxH (16px multiples, each edge ≤3840, ratio ≤3:1). (default: auto)
`quality`	No	Image quality level (default: auto)
`output_format`	No	Output image format (default: png)
`moderation`	No	Content moderation level (default: auto)
`sample_count`	No	Number of images to generate (1-10, default: 1)
`return_base64`	No	Return base64 image data in response (default: false)
`include_thumbnail`	No	Include thumbnail preview in MCP response for LLM recognition (default: false, overrides OPENAI_IMAGE_THUMBNAIL env var)
`input_fidelity`	No	Input fidelity for preserving faces/logos. gpt-image-1.5 only (gpt-image-2 is always high, gpt-image-1 unsupported). High uses more tokens. (default: low)

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description carries full burden. Discloses inpainting method, need for reference image, optional mask (transparent areas edited), model-specific input_fidelity behavior, default model. Missing edge cases like handling of multiple inputs, but key behaviors covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with purpose, followed by key behavioral detail. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description covers key aspects: input requirements, model differences, optional mask. Could include return value format, but for 15-param tool with 100% schema coverage, it's nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. Description adds value by explaining model-specific behavior for input_fidelity and mask semantics ('transparent areas are edited'). Provides context beyond what schema gives.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Edit an existing image using inpainting' with specific verb and resource. Distinguishes from siblings like generate_image (creates new) and transform_image (different operation). High clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. Usage is implied (for editing existing images with inpainting), but no contrast with sibling tools like generate_image or start_generation_job. Baseline implied usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageA

Generate a new image from a text prompt using OpenAI GPT image models. Supports gpt-image-1, gpt-image-1.5 (4x faster/cheaper, better text), and gpt-image-2 (flexible sizes up to 4K). Automatically calculates and reports token usage and cost.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	The text prompt describing the image to generate
`output_path`	No	Output file path (default: generated_image.png)
`model`	No	Model to use. gpt-image-2: latest, flexible sizes up to 4K (3840/2160 experimental), no transparent_background. gpt-image-1.5: 4x faster, 20% cheaper, supports input_fidelity. gpt-image-1: original. (default: gpt-image-1)
`size`	No	Image size. gpt-image-1/1.5 only support 1024x1024, 1024x1536, 1536x1024, auto. gpt-image-2 also supports 2K/4K presets plus custom WxH (16px multiples, each edge ≤3840, ratio ≤3:1). 3840x2160/2160x3840 are experimental. (default: auto)
`quality`	No	Image quality level (default: auto)
`output_format`	No	Output image format (default: png)
`transparent_background`	No	Enable transparent background (PNG only, default: false). Not supported by gpt-image-2.
`moderation`	No	Content moderation level (default: auto)
`sample_count`	No	Number of images to generate (1-10, default: 1)
`return_base64`	No	Return base64 image data in response (default: false)
`include_thumbnail`	No	Include thumbnail preview in MCP response for LLM recognition (default: false, overrides OPENAI_IMAGE_THUMBNAIL env var)

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses use of OpenAI models, automatic token/cost calculation, and multiple model capabilities. However, it does not mention overwrite behavior for output_path, rate limits, or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose and model list. No unnecessary words, but the model details could be more structured. Still, it is efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain return values. It mentions optional base64 and thumbnail but does not clarify the default return (presumably saved file path and token usage?). While model details are good, the output behavior is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already describes all parameters. The description adds modest value by summarizing model version differences and auto-calculation of costs, but this information is largely redundant with the enum descriptions in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates images from text prompts using specific OpenAI models. It distinguishes itself from siblings like edit_image and transform_image by focusing on generation from scratch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides model selection guidance but does not explicitly state when to use this tool versus alternatives like start_generation_job (async vs sync). The model descriptions help choose among models but no explicit when-not or sibling differentiation beyond model choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_history_by_uuidA

Get detailed information about a specific generation history record by UUID. Shows complete parameters, prompt, and all output files.

ParametersJSON Schema

Name	Required	Description	Default
`uuid`	Yes	History record UUID

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It states the tool reads history and returns detail, implying read-only behavior. However, it does not mention authentication, permissions, or any side effects. The description is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence (25 words). It front-loads the main action and then lists contents. Every word adds value; no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one param, no output schema, no annotations), the description covers the essential: what it does and what it returns. Additional context like response structure or limits would be nice but not critical. The description is complete enough for a straightforward lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (parameter uuid described as 'History record UUID'). The description reinforces that the tool looks up by UUID but adds no new semantics beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a specific generation history record by UUID and lists what it shows (parameters, prompt, output files). This distinguishes it from sibling tools like list_history (summary) and get_job_result (different entity).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you have a UUID and need detailed history, but does not explicitly say when to use or avoid it vs alternatives like list_history or get_job_result. No exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_job_resultA

Get the result of a completed async job. Returns output file paths and history UUID. Only works for completed jobs.

ParametersJSON Schema

Name	Required	Description	Default
`job_id`	Yes	Job ID

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It reveals the tool is a read operation, requires a completed job, and returns specific outputs. It adds value beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no unnecessary words. Purpose is front-loaded, followed by return info and constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter tool with no output schema, the description covers purpose, constraint, and return values adequately. Sibling context further clarifies its role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (job_id with 'Job ID'). The description adds no extra semantic detail beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'result of a completed async job', and specifies what is returned (output file paths and history UUID). It distinguishes from sibling tools like check_job_status and cancel_job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes 'Only works for completed jobs,' implying the prerequisite. While it doesn't name an alternative, it provides clear context on when to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_metadata_from_imageA

Extract and display embedded metadata from a generated image file. Shows UUID, parameter hash, generation settings, and verifies integrity with database. Works with PNG and JPEG images that contain embedded OpenAI GPT-Image metadata.

ParametersJSON Schema

Name	Required	Description	Default
`image_path`	Yes	Path to the image file to read metadata from

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses key behaviors: it shows specific metadata fields and verifies integrity with a database. It implies read-only operation by using 'extract and display' and specifies file format support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences, front-loaded with the core action, and every sentence contributes essential information without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, no output schema), the description adequately covers what the tool does, what it returns, and applicable file types. It could mention error cases but is still sufficient for correct use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'image_path' is fully described in the schema (100% coverage). The description adds context by specifying that the path should point to a generated image with OpenAI metadata, which enriches the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: extract and display embedded metadata from generated images. It specifies the actions (shows UUID, parameter hash, etc.) and differentiates from sibling tools like generate_image or edit_image by focusing on metadata retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use the tool (on PNG/JPEG images with embedded OpenAI metadata) but does not explicitly state when not to use or provide alternatives. Since no other tool extracts metadata, the context is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_generated_imagesB

List all image files in a directory. Shows file names, sizes, and modification dates sorted by newest first.

ParametersJSON Schema

Name	Required	Description	Default
`directory`	No	Directory path to search (default: current directory)

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so description bears full burden. It discloses that the listing is sorted newest first and includes names/sizes/dates, but does not address edge cases (e.g., non-existent directory), permissions, or whether it only scans the top level or recurses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the core purpose and key details (list all image files, shows names/sizes/dates, sorted newest first). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although no output schema is provided, the description adequately explains the return content (file names, sizes, dates, sorted order). It could be more complete by specifying what qualifies as an image file, but covers the essentials given the simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description reinforces that the directory parameter specifies where to list files, but adds no new detail beyond the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists image files in a directory, showing names, sizes, and modification dates sorted by newest first. This is specific and distinguishes it from sibling tools like list_history (history) and list_jobs (jobs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., list_history, list_jobs). No 'when not to use' or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_historyB

List generation history with optional filters. Shows recent image generation, editing, and transformation operations with their parameters and output files.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of records to return (1-100, default: 20)
`offset`	No	Number of records to skip (default: 0)
`tool_name`	No	Filter by specific tool
`query`	No	Search in prompt text

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It states the tool shows 'parameters and output files' but does not mention read-only nature, rate limits, pagination behavior beyond what's in schema, or data freshness. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence of 20 words, extremely concise. Front-loaded with the key action 'List generation history'. Every word earns its place. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 4 optional filters, no output schema, and lists potentially complex history. The description notes it shows 'parameters and output files' but omits other likely fields like timestamps, status, user, etc. Without an output schema, more detail is needed for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all parameters have descriptions). The description adds context that the tool shows 'recent...operations with their parameters and output files', but this adds marginal value beyond the schema which already describes each parameter clearly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List generation history' with specific verb and resource, and mentions the types of operations (image generation, editing, transformation). It naturally distinguishes from sibling tools like get_history_by_uuid (which gets a single entry) and list_jobs (different scope).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No explicit conditions, prerequisites, or mentions of when not to use it. Sibling tools include get_history_by_uuid, list_jobs, etc., but no comparative advice is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_jobsB

List async jobs with optional filters. Shows job status, progress, creation time, and output information.

ParametersJSON Schema

Name	Required	Description
`status`	No	Filter by status
`tool_name`	No	Filter by tool
`limit`	No	Max results (1-100, default: 20)
`offset`	No	Skip N results

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions returned fields (status, progress, creation time, output information) which adds value, but does not disclose pagination, ordering, or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description covers basic return information but omits pagination details and overall response structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists async jobs with optional filters, which is distinct from siblings like cancel_job and check_job_status. However, it does not explicitly differentiate from list_history, which might be similar.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like check_job_status or get_job_result. The description lacks context on when to apply filters or best practices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_generation_jobA

Start an async image generation job that runs in the background. Use this for long-running operations or when you want to queue multiple generations. Returns a job ID that can be used to check status and retrieve results.

ParametersJSON Schema

Name	Required	Description
`tool_name`	Yes	Which image tool to use
`prompt`	Yes	The generation prompt
`output_path`	No	Output file path
`model`	No	Model to use (default: gpt-image-1)
`size`	No	Image size. gpt-image-2 also supports custom WxH (16px multiples, each edge ≤3840, ratio ≤3:1).
`quality`	No	Image quality
`output_format`	No	Output format
`sample_count`	No	Number of images (1-10)
`input_fidelity`	No	Input fidelity for edit/transform. gpt-image-1.5 only; gpt-image-2 is always high (field ignored).

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses async and background nature but does not mention side effects, rate limits, or permissions. With no annotations, description carries full burden but misses some behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no fluff. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a 9-parameter tool with no output schema and no annotations. Covers core use, return value, and async behavior, though could mention integration with status/result tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description does not add meaningful parameter-level details beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool starts an async image generation job that runs in the background and returns a job ID. Differentiates from sibling tools like generate_image (sync) by emphasizing async and background execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using this tool for long-running operations or queuing multiple generations. Implies alternatives exist (e.g., synchronous tools) but does not explicitly list when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

transform_imageB

Transform an existing image to a new style or interpretation using OpenAI GPT image models. Takes a reference image and a prompt describing the desired transformation. gpt-image-1.5 supports input_fidelity for better face/logo preservation.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	Description of the desired transformation
`reference_image_base64`	No	Base64 encoded reference image
`reference_image_path`	No	Path to reference image file
`output_path`	No	Output file path (default: transformed_image.png)
`model`	No	Model to use. gpt-image-2: latest, flexible sizes, input_fidelity is auto-high (field ignored). gpt-image-1.5: supports input_fidelity. gpt-image-1: original. (default: gpt-image-1)
`size`	No	Image size. gpt-image-1/1.5 only support 1024x1024, 1024x1536, 1536x1024, auto. gpt-image-2 also supports 2K/4K presets plus custom WxH (16px multiples, each edge ≤3840, ratio ≤3:1). (default: auto)
`quality`	No	Image quality level (default: auto)
`output_format`	No	Output image format (default: png)
`moderation`	No	Content moderation level (default: auto)
`sample_count`	No	Number of images to generate (1-10, default: 1)
`return_base64`	No	Return base64 image data in response (default: false)
`include_thumbnail`	No	Include thumbnail preview in MCP response for LLM recognition (default: false, overrides OPENAI_IMAGE_THUMBNAIL env var)
`input_fidelity`	No	Input fidelity for preserving faces/logos. gpt-image-1.5 only (gpt-image-2 is always high, gpt-image-1 unsupported). High uses more tokens. (default: low)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility. It mentions a model-specific feature (input_fidelity) but does not disclose general behavior such as output format, error handling, or side effects. The short description leaves significant gaps in understanding the tool's full behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loading the core purpose and adding one key detail. No fluff, every sentence is informative and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 13 parameters and no output schema, the description is brief. It covers the core transformation action but lacks information about return values, error conditions, or behavior across models. The detailed schema helps, but the description could be more complete to guide usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds context about input_fidelity for face/logo preservation, which goes beyond the schema. However, it does not add meaning for other parameters, so it remains at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool transforms an existing image using a prompt, which distinguishes it from generate_image (from scratch) and edit_image (specific edits). The verb 'transform' and resource 'existing image' are specific, but it could more explicitly contrast with sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like edit_image or generate_image. It describes what the tool does but not when or when not to use it, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

12 tool updatesv1.4.0Jun 18, 2026
- First observedcancel_job
- First observedcheck_job_status
- First observededit_image
- First observedgenerate_image
- First observedget_history_by_uuid
- First observedget_job_result
- First observedget_metadata_from_image
- First observedlist_generated_images
- First observedlist_history
- First observedlist_jobs
- First observedstart_generation_job
- First observedtransform_image

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool targets a distinct operation: image generation, editing, transformation, async job management, history retrieval, and metadata extraction. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow consistent verb_noun snake_case pattern (e.g., generate_image, cancel_job, list_history). No mixing of styles.

Tool Count5/5

12 tools is an appropriate scope for a dedicated image generation server, covering creation, editing, async jobs, and history without being excessive.

Completeness4/5

Core operations (create, edit, transform, async management, history) are covered. Missing deletion capabilities (e.g., delete_image, delete_history), but these are minor gaps.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

APICK AI A
app.apick
LLM chat, text tools, image generation, editing and batch image jobs
AI & Machine Learning Image & Video Processing
911
Codex Imagem A
io.github.mcp-dir
Generate images with your own ChatGPT subscription (Plus, Pro or Team), without spending API credits
AI & Machine Learning Image & Video Processing
81
fengyinxia-jimeng-mcp
ai.smithery
Create images and videos from prompts, with options for image mixing, reference images, and start/…
Image & Video Processing Multimedia Processing
2
imageatOAuth
io.github.incendies
Generate and edit images and videos with imageat.
Image & Video Processing Multimedia Processing
1

Related MCP Servers

AI Image MCP Server
Image & Video Processing
kareemaly
A
license
Not graded
quality
C
maintenance
Enables AI-powered image analysis using OpenAI's Vision API and image generation with DALL-E models. Supports image description, content analysis, comparison, editing, and creating variations with intelligent caching.
Updated a year ago (2025-06-26 16:46 UTC)
3
MIT
openai-imagegen-mcp
Image & Video Processing AI & Machine Learning
marabian
F
license
Not graded
quality
D
maintenance
Enables image generation and editing via OpenAI's gpt-image-1 model, with options for saving, format control, and transparency.
Updated a year ago (2025-08-12 04:23 UTC)
-
GPT-Image MCP Server
AI & Machine Learning Image & Video Processing
IronManCantFix
A
license
B
quality
B
maintenance
Enables generating images from text or transforming existing images using GPT-Image-compatible APIs, with support for OpenAI and Agnes AI backends.
Updated a month ago (2026-07-28 06:11 UTC)
2
MIT
GPT Image 2 Polza MCP Server
AI & Machine Learning Image & Video Processing
ivanantigravity-lgtm
A
license
B
quality
C
maintenance
Enables generating and editing images using OpenAI's GPT Image 2 model via the Polza API, with support for multiple modes, reference images, and local file storage.
Updated 3 months ago (2026-06-15 18:22 UTC)
5
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ex-takashima/openAI-gpt-image-1-MCP-SERVER'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

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

Available Tools

Tool Schema Changelog

Maintenance

Resources

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`