GPT Image Server

PyPI version Python versions License: MIT CI 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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs/ directory for detailed guides

---

Happy image generating! 🎨✨