MCP server for OpenAI GPT Image API - Generate and edit images using gpt-image-1 and gpt-image-1.5
npm install openai-gpt-image-mcp-serverbash
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
``