Skip to main content
Glama
labeveryday

GPT Image MCP Server

by labeveryday
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

GPT Image MCP Server

PyPI version Python versions License: MIT CI MCP

gpt-image-mcp

A Model Context Protocol (MCP) server for image generation, editing, and analysis powered by OpenAI's gpt-image-1 model. Built with FastMCP — generate YouTube thumbnails, blog headers, social media images, or any custom image, with optional reference-image support and platform-aware optimization.

📦 Install

pip install gpt-image-mcp
# or
uv add gpt-image-mcp

Set OPENAI_API_KEY in your environment, then run:

gpt-image-mcp

🎯 Perfect for Content Creators: Generate professional thumbnails with your photo automatically positioned and branded consistently, or get creative when you want variety.

🌟 Features

🎯 Specialized Content Generation

  • YouTube Thumbnails: Optimized for engagement (1536×1024 landscape format)

  • Blog Images: Professional headers and featured images

  • Social Media: Platform-optimized content for Instagram, Twitter, Facebook

  • General Purpose: Flexible image generation for any use case

🖼️ Reference Image Integration

  • Personal Branding: Use your photos to create consistent thumbnails

  • Style Preservation: Maintains facial features and appearance from reference images

  • Custom Layouts: Generate thumbnails in your established style (positioning, text placement, colors)

  • High Input Fidelity: Advanced reference image processing for accurate results

  • Creative Flexibility: Choose between consistent branding or creative freedom

  • Multiple Composition Styles: Centered, dynamic, left/right positioning, or fully experimental

🚀 Advanced AI Integration

  • GPT-Image-1 Support: Uses OpenAI's latest and best image generation model

  • Multi-Model Fallback: Automatic fallback to DALL-E 3 for reliability

  • Smart Prompt Optimization: Enhanced prompts based on content type

  • Batch Processing: Generate multiple images concurrently

🎨 Platform Intelligence

  • Auto-Sizing: Intelligent size selection based on content type

  • Style Variants: Professional, casual, dramatic, minimalist, educational

  • Emotional Tones: Excited, confident, friendly, serious, and more

  • Brand Integration: Custom color schemes and consistent styling

📊 Analysis & Optimization

  • Effectiveness Scoring: Thumbnail analysis with 0-10 effectiveness scoring

  • Platform Optimization: Convert images for specific platforms

  • Improvement Suggestions: Actionable recommendations for better performance

  • Best Practices: Built-in knowledge of platform requirements

📦 Installation

Prerequisites

  • Python 3.11+

  • OpenAI API key with GPT-Image-1/DALL-E 3 access

  • UV package manager (recommended)

Quick Start

# Clone the repository
git clone https://github.com/labeveryday/gpt-image-mcp.git
cd gpt-image-mcp

# Install dependencies
uv sync

# Configure your API key
cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=your_key_here

# Test the installation
uv run python demo.py

🚀 Usage

MCP Client Integration (Recommended)

This server is designed to work with MCP clients like Claude Code. Add it to your MCP configuration:

{
  "name": "gpt-image-mcp",
  "command": "uv",
  "args": ["run", "gpt-image-mcp"],
  "cwd": "/path/to/gpt-image-mcp"
}

Quick MCP Examples

Once connected, you can simply ask Claude:

🎯 "Generate a YouTube thumbnail for my Python tutorial"
→ Creates professional thumbnail (default strict mode)

🎨 "Generate a creative YouTube thumbnail with me centered"  
→ Uses creative mode with centered composition

📸 "Generate a thumbnail using my photo with 'LEARN CODING' text"
→ Uses reference image with professional layout

🚀 "Be experimental with the layout and try something artistic"
→ Uses experimental creative mode for unique designs

Starting the MCP Server (Manual)

# Start with UV (recommended)
uv run gpt-image-mcp

# Or run the server directly
uv run python src/gpt_image_mcp/server.py

Demo Usage

# Run the demo to test functionality
uv run python demo.py

# Test individual features
uv run python -c "from demo import demo_youtube_thumbnail; import asyncio; asyncio.run(demo_youtube_thumbnail())"

🛠️ Available Tools

1. generate_image - Primary Image Generation

Generate optimized images for any platform or purpose.

{
  "prompt": "Excited tech reviewer with the latest gadget, studio lighting",
  "content_type": "youtube_thumbnail",
  "style": "professional", 
  "emotional_tone": "excited",
  "size": "1536x1024",
  "include_text_overlay": true,
  "text_overlay": "Amazing New Tech!",
  "brand_colors": ["#FF6B6B", "#4ECDC4"],
  "reference_image": "/path/to/your/photo.jpg",  // File path or base64 data
  "creative_mode": false,
  "composition_style": "right",
  "layout_freedom": "standard"
}

2. generate_reference_thumbnail - Personal Branding

Create thumbnails using your photo in your established style.

{
  "reference_image": "/Users/me/photos/headshot.png",  // File path or base64 data
  "main_text": "5 TECH SIDE HUSTLES",
  "secondary_text": "THAT MAKE $10K/MONTH", 
  "topic": "entrepreneurship",
  "style_override": "professional",
  "creative_mode": false,
  "composition_style": "right",
  "layout_freedom": "standard"
}

3. analyze_thumbnail - AI-Powered Analysis

Get effectiveness scores and improvement suggestions.

{
  "image_data": "base64_encoded_image_data",
  "platform": "youtube",
  "content_category": "education"
}

4. optimize_for_platform - Platform Conversion

Adapt existing images for different platforms.

{
  "image_data": "base64_encoded_image_data", 
  "target_platform": "instagram",
  "optimization_focus": ["engagement", "readability"]
}

5. generate_batch - Bulk Generation

Generate multiple images efficiently.

{
  "requests": [
    {"prompt": "Tutorial thumbnail 1", "content_type": "youtube_thumbnail"},
    {"prompt": "Tutorial thumbnail 2", "content_type": "youtube_thumbnail"}
  ],
  "max_concurrent": 3
}

6. get_prompt_suggestions - Prompt Enhancement

Get AI suggestions for better prompts.

{
  "content_type": "youtube_thumbnail",
  "current_prompt": "Python tutorial video"
}

📐 Supported Sizes & Platforms

Platform

Optimal Size

Aspect Ratio

Notes

YouTube

1792×1024

~16:9

OpenAI supported landscape

Instagram

1024×1024

1:1

Square format

Twitter

1792×1024

~16:9

Wide landscape format

Facebook

1792×1024

~16:9

Cover images

Blog Header

1792×1024

~16:9

Professional headers

Blog Featured

1024×1792

~9:16

Portrait format

All sizes use OpenAI's currently supported dimensions: 1024×1024, 1024×1792, and 1792×1024.

📸 Reference Image Handling

File Path Support

Reference images can be provided as either file paths or base64 encoded data:

// Using file paths (recommended - automatic resizing)
"reference_image": "/Users/you/photos/headshot.jpg"
"reference_image": "./images/profile.png"
"reference_image": "/home/user/pictures/photo.jpg"

// Using base64 data (backward compatibility)
"reference_image": "iVBORw0KGgoAAAANSUhEUgAA..."

Automatic Image Processing

  • Large Image Handling: Input images over 2MB are automatically resized

  • Format Support: JPEG, PNG, WebP, and other common formats

  • Size Optimization: YouTube thumbnails are optimized to stay under 2MB

  • Quality Preservation: Smart resizing maintains image quality

🎨 Content Types & Styles

Content Types

  • youtube_thumbnail - High-impact video thumbnails (auto-optimized under 2MB)

  • blog_header - Professional article headers

  • blog_featured - Featured/hero images

  • social_media - General social content

  • general - Flexible general-purpose images

Styles

  • professional - Clean, business-appropriate

  • casual - Relaxed, approachable

  • dramatic - High-contrast, bold

  • minimalist - Simple, elegant

  • educational - Clear, instructional

  • entertainment - Fun, engaging

Emotional Tones

  • excited - High energy, enthusiastic

  • confident - Strong, authoritative

  • friendly - Warm, approachable

  • curious - Intriguing, mysterious

  • serious - Professional, formal

  • surprised - Attention-grabbing

  • dramatic - Intense, compelling

Creative Mode System

🔒 DEFAULT: Strict Professional Mode

  • creative_mode=False (default) - Consistent, reliable professional layouts

  • Person positioned right, text on left, red banner for emphasis

  • Perfect for consistent branding and professional thumbnails

  • This is the recommended default for most users

🎨 CREATIVE MODE: When You Want Variety

  • creative_mode=True - Unlocks flexible and experimental options

  • Only activated when you specifically request creative freedom

Layout Freedom Levels (when creative_mode=True)

  • standard - Consistent branding (same as strict mode)

  • flexible - Some creative freedom while maintaining best practices

  • experimental - Complete creative freedom with unconventional designs

Composition Styles (when creative_mode=True)

  • left - Position person on the left side

  • right - Position person on the right side

  • centered - Center the person prominently

  • dynamic - Use energetic, dynamic positioning

  • creative - Experiment with artistic composition techniques

Usage Patterns

# Professional consistency (RECOMMENDED DEFAULT)
# Just use the tool without creative parameters

# Creative with structure  
creative_mode=True, layout_freedom="flexible", composition_style="centered"

# Full creative freedom
creative_mode=True, layout_freedom="experimental", composition_style="creative"

💾 File Storage

Temporary Image Storage

Generated images are automatically saved to cross-platform temporary directories:

  • macOS: /var/folders/.../gpt-image-mcp/

  • Windows: C:\Users\{user}\AppData\Local\Temp\gpt-image-mcp\

  • Linux: /tmp/gpt-image-mcp/

Automatic Cleanup:

  • Files older than 24 hours are automatically deleted

  • Cleanup runs on server startup and via the cleanup_temp_files tool

  • Unique filenames prevent conflicts: image_20250825_142324_3566695c.png

Manual Management:

# Check temp directory status
uv run python -c "from src.gpt_image_mcp.file_manager import temp_image_manager; print(temp_image_manager.get_temp_dir_info())"

# Clean up old files manually
uv run python -c "from src.gpt_image_mcp.file_manager import temp_image_manager; print(f'Cleaned {temp_image_manager.cleanup_old_files()} files')"

🔧 Configuration

Environment Variables (.env)

# Required
OPENAI_API_KEY=your_openai_api_key

# Optional - Model Configuration
DEFAULT_MODEL=gpt-image-1               # Primary model (OpenAI's best)
IMAGE_MODEL=gpt-image-1                 # Direct image model  
FALLBACK_MODEL=dall-e-3                 # Fallback option

# Optional - Performance
MAX_CONCURRENT_GENERATIONS=5            # Batch processing limit
TIMEOUT_SECONDS=120                     # Request timeout
RATE_LIMIT_PER_MINUTE=30               # API rate limiting

# Optional - Quality  
DEFAULT_QUALITY=auto                    # Image quality
ENABLE_COMPRESSION=true                 # File size optimization
MAX_IMAGE_SIZE_MB=10.0                 # Size limits

# Optional - Logging
LOG_LEVEL=INFO                         # DEBUG for verbose logging
ENABLE_DETAILED_LOGGING=false          # Request/response logging

📋 Examples

MCP Usage with Claude (Recommended)

Simply ask Claude naturally - the MCP server will handle the technical details:

👤 "Generate a YouTube thumbnail for my Python tutorial with 'MASTER PYTHON FAST' text"

🤖 Claude creates professional thumbnail with:
   - Your photo positioned on the right  
   - Bold white text on the left
   - Red banner for emphasis
   - Professional dark background

👤 "Be creative with the layout and center me in the composition"

🤖 Claude uses creative_mode=True, composition_style="centered" for artistic variety

👤 "Generate 5 different thumbnail variations for my coding series"

🤖 Claude uses batch generation with different styles and compositions

Direct API Usage (Advanced)

Professional Consistent Thumbnail (Default)

{
    "prompt": "Professional YouTube thumbnail about Python programming",
    "content_type": "youtube_thumbnail", 
    "text_overlay": "MASTER PYTHON FAST!",
    "reference_image": "base64_encoded_headshot"
}

Creative Experimental Thumbnail

{
    "prompt": "Creative coding tutorial thumbnail",
    "content_type": "youtube_thumbnail",
    "text_overlay": "CODE CREATIVELY",
    "reference_image": "base64_encoded_headshot",
    "creative_mode": true,
    "layout_freedom": "experimental",
    "composition_style": "dynamic"
}

Standard YouTube Thumbnail (No Reference)

request = {
    "prompt": "Enthusiastic developer coding Python, modern setup, vibrant colors",
    "content_type": "youtube_thumbnail", 
    "style": "professional",
    "emotional_tone": "excited",
    "text_overlay": "Master Python Fast!",
    "brand_colors": ["#3776ab", "#ffd343"]  # Python colors
}

Blog Header Image

request = {
    "prompt": "Modern digital workspace with analytics and growth charts",
    "content_type": "blog_header",
    "topic": "business growth",
    "target_audience": "entrepreneurs", 
    "style": "professional"
}

Social Media Post

request = {
    "prompt": "Cozy coffee shop workspace with laptop and notebook",
    "content_type": "social_media",
    "style": "casual",
    "emotional_tone": "friendly",
    "size": "1024x1024"  # Instagram square
}

🧪 Testing & Development

Test Reference Image Functionality

# Test with sample superhero image
uv run examples/superhero_thumbnail_test.py

# Test with your own photo
uv run examples/test_reference_thumbnail.py /path/to/your/photo.jpg

# Demo creative mode options (no API calls)
uv run examples/demo_creative_modes.py

# Test all creative modes (requires API key)
uv run examples/test_creative_modes.py

# Run demo for general testing
uv run python demo.py

Run Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/gpt_image_mcp

# Test specific functionality
uv run python demo.py

Code Quality

# Format code  
uv run black src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type checking
uv run mypy src/

Development Server

# Start in development mode with detailed logging
LOG_LEVEL=DEBUG ENABLE_DETAILED_LOGGING=true uv run python src/gpt_image_mcp/server.py

🤖 Integration Examples

Direct MCP Usage

import asyncio
from mcp import ClientSession, stdio_client, StdioServerParameters

async def generate_thumbnail():
    async with stdio_client(StdioServerParameters(
        command="uv", args=["run", "gpt-image-mcp"]
    )) as (read, write):
        async with ClientSession(read, write) as client:
            result = await client.call_tool("generate_image", {
                "prompt": "Amazing tech review thumbnail",
                "content_type": "youtube_thumbnail"
            })
            return result

# Run it
result = asyncio.run(generate_thumbnail())

Claude Code Integration

The server integrates seamlessly with Claude Code for AI-powered content creation workflows.

🔍 Troubleshooting

Common Issues

API Key Errors

# Verify your API key is set
echo $OPENAI_API_KEY

# Check API key validity
uv run python -c "import openai; print(openai.api_key)"

Image Generation Fails

  • Simplify complex prompts

  • Check API credits and rate limits

  • Try fallback models (DALL-E 3)

Large File Sizes

  • Enable compression: ENABLE_COMPRESSION=true

  • Reduce quality: DEFAULT_QUALITY=medium

  • Check size limits: MAX_IMAGE_SIZE_MB=10

Rate Limiting

  • Adjust concurrent requests: MAX_CONCURRENT_GENERATIONS=3

  • Increase timeout: TIMEOUT_SECONDS=180

  • Lower rate limit: RATE_LIMIT_PER_MINUTE=20

Debug Mode

# Enable verbose logging
LOG_LEVEL=DEBUG ENABLE_DETAILED_LOGGING=true uv run gpt-image-mcp

# Check server health
uv run python -c "from src.gpt_image_mcp.config import settings; print(settings)"

📈 Performance Notes

  • OpenAI API Compatibility: Uses OpenAI-supported image dimensions (1024×1024, 1792×1024, 1024×1792)

  • Optimized Tool Schemas: Simplified models for better MCP client compatibility

  • Batch Processing: Use generate_batch for multiple images

  • Fallback Strategy: Automatic model fallback ensures reliability

🤝 Contributing

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Make changes with proper Pydantic validation

  4. Add tests for new functionality

  5. Run code quality checks: uv run black src/ && uv run ruff check src/

  6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with FastMCP for clean MCP server architecture

  • Powered by OpenAI GPT and DALL-E models

  • Uses Pydantic for robust data validation

  • Package management with UV

📞 Support

Happy image generating! 🎨✨

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Latest Blog Posts

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/labeveryday/gpt-image-mcp'

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