Skip to main content
Glama
labeveryday

GPT Image MCP Server

by labeveryday
OverviewSchemaSourceRelated ServersDiscussionsAdmin
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.

Related MCP server: GPT Image MCP Server

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

Available Tools

7 tools
analyze_thumbnailA

Analyze a thumbnail's effectiveness and provide improvement suggestions.

Args: image_data: Base64 encoded image data platform: Platform for analysis (youtube, instagram, twitter, facebook, blog) content_category: Content category (e.g., education, entertainment, tech)

ParametersJSON Schema
NameRequiredDescriptionDefault
platformNoyoutube
image_dataYes
content_categoryNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description must fully disclose behavior. It mentions analysis and suggestions but doesn't clarify what happens to the image data, whether it's stored, how 'effectiveness' is measured, or any limitations. This leaves significant gaps for an agent deciding whether to invoke the tool.

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 concise and front-loaded with the core purpose, followed by a compact argument list. Every sentence contributes value, and there is no redundant or filler content.

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 an output schema, so return values don't need explanation. However, the description omits important context like whether platform and content_category are optional (schema shows platform has a default and content_category can be null), and it doesn't mention any prerequisites or error scenarios. It's minimally viable but not fully 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?

The schema has 0% description coverage, so the description must compensate, and it does. It clearly explains each parameter: image_data as 'Base64 encoded image data', platform with example values, and content_category with examples. This adds meaningful semantics beyond the bare schema, though it could be more precise about format or optionality.

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 function: 'Analyze a thumbnail's effectiveness and provide improvement suggestions.' This uses a specific verb ('analyze') and resource ('thumbnail's effectiveness'), and distinguishes it from sibling tools like generate_image and optimize_for_platform by focusing on evaluation rather than creation or optimization.

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 when to use the tool—when you need to assess a thumbnail and receive suggestions—but it doesn't explicitly compare it to alternatives like optimize_for_platform. It provides clear context but no exclusions or direct 'when to use' guidance, so it falls short of the ideal.

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

cleanup_temp_filesB

Clean up old temporary files.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It implies deletion of files but does not state that this is destructive, irreversible, or what criteria define 'old'. No side effects or permission requirements are mentioned, leaving significant behavioral ambiguity.

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 a single sentence with no filler, making it efficient and front-loaded. It could be slightly more informative, but as a concise statement of purpose, it earns its place.

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 description is too sparse for a destructive cleanup tool. It does not explain what files are affected, the safety profile, when to run it, or any return values (though the output schema exists). The overall context is incomplete for safe and correct usage.

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 tool has zero parameters, so the schema provides no parameter details. Per the baseline for 0 params, a score of 4 is appropriate. The description adds no parameter info, but none is needed.

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 action ('clean up') and the resource ('old temporary files'). This is a specific verb+resource combo that distinguishes it from the unrelated sibling tools, which all deal with image generation/analysis.

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 is provided on when to use this tool, prerequisites, or exclusions. The sibling tools are unrelated, so there is no alternative to contrast with, but the description still fails to convey any usage context beyond the basic action.

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

generate_batchA

Generate multiple images at once with different parameters.

Args: requests: List of image generation requests (each with prompt, content_type, etc.) max_concurrent: Maximum number of concurrent generations (1-10)

ParametersJSON Schema
NameRequiredDescriptionDefault
requestsYes
max_concurrentNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions the concurrency limit range (1-10) but does not describe error handling, return behavior, or other side effects. Some context is provided, but deeper traits are missing.

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 concise and front-loaded with the core purpose. The Args block efficiently documents parameters without redundancy or irrelevant details.

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 an output schema and parameters are well explained, but the description lacks usage guidance relative to siblings and does not address potential batch size limits or failure behavior. It covers the essentials but leaves gaps for an agent to fully understand when to use this tool.

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

Parameters5/5

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

The input schema lacks meaningful descriptions (0% coverage), but the description explicitly explains both parameters: requests (list of generation requests) and max_concurrent (concurrency range 1-10). This adds significant value beyond the schema's type and title information.

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 a specific action ('Generate multiple images at once') and distinguishes it from single-image generation by its batch nature. It identifies the resource (images) and the differentiation from sibling tools like generate_image.

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 usage for batch generation with different parameters, but it does not explicitly state when to prefer this tool over alternatives like generate_image. No exclusions or alternative references are provided.

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

generate_imageA

Generate images using OpenAI gpt-image-1 for YouTube thumbnails, blog images, and social media content.

This tool generates completely new images from text descriptions. For incorporating reference images (especially for YouTube thumbnails with people), use generate_reference_thumbnail instead.

Args: prompt: Description of the image to generate content_type: Type of content (youtube_thumbnail, blog_header, blog_featured, social_media, general) size: Image dimensions (auto-selected based on content_type if not provided) quality: Image quality level (low, medium, high, auto) style: Visual style (professional, casual, dramatic, minimalist, educational, entertainment) emotional_tone: Emotional tone (excited, curious, confident, surprised, serious, friendly, dramatic) include_text_overlay: Whether to include text overlay on the image text_overlay: Text to overlay on the image brand_colors: Brand colors to use (hex codes) topic: Topic or subject matter for the image target_audience: Target audience for the content avoid_elements: Elements to avoid in the generated image emphasis_elements: Elements to emphasize in the generated image reference_image: Reference image - must be either a file path (e.g., "/path/to/image.jpg") or base64 encoded image data. Claude's "[Image #1]" format is not supported - save the image to a file first. creative_mode: Enable creative freedom vs. structured layouts (default: False for consistent branding) composition_style: Composition approach (centered, left, right, dynamic, creative, or None for auto) layout_freedom: Layout constraints (standard=consistent branding, flexible=some creativity, experimental=full freedom)

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNoauto
styleNo
topicNo
promptYes
qualityNoauto
brand_colorsNo
content_typeNogeneral
text_overlayNo
creative_modeNo
avoid_elementsNo
emotional_toneNo
layout_freedomNostandard
reference_imageNo
target_audienceNo
composition_styleNo
emphasis_elementsNo
include_text_overlayNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it explains the tool generates new images (not edits), details reference_image format restrictions (file path/base64, no Claude image format), and describes creative_mode/layout_freedom behavioral differences. However, it does not disclose potential issues like API costs, rate limits, or error 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 front-loaded with a clear purpose and sibling differentiation, then follows with a structured Args list. Every sentence adds value, and while long, the length is justified by 17 parameters needing explanation. There is no repetition of schema fields beyond what is necessary.

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 tool with 17 parameters and no annotations, the description is remarkably complete. It covers the tool's purpose, content types, when to use an alternative, and enriches every parameter with semantic detail. The presence of an output schema means return-value documentation is not required, so no major gaps remain.

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

Parameters5/5

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

Schema coverage is 0%, and the description compensates by documenting all 17 parameters in the Args list with clear meanings and allowed values. For example, size is 'auto-selected based on content_type,' quality lists low/medium/high/auto, style provides visual style options, and reference_image includes format constraints. This fully bridges the gap left by 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 it generates images using OpenAI gpt-image-1 for YouTube thumbnails, blog images, and social media content, and explicitly says it creates 'completely new images from text descriptions.' It also distinguishes itself from the sibling tool generate_reference_thumbnail by noting that tool is for incorporating reference images, giving it a clear identity.

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 gives explicit guidance for when to use this tool vs. generate_reference_thumbnail: 'For incorporating reference images (especially for YouTube thumbnails with people), use generate_reference_thumbnail instead.' It also implies general use cases. However, it does not mention other sibling tools like optimize_for_platform or generate_batch, so not fully covers all alternatives.

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

generate_reference_thumbnailA

SPECIALIZED tool for YouTube thumbnails using reference images with predefined layouts.

Use this tool specifically for YouTube thumbnails when you want the standard thumbnail layout (person on right, text on left, red banner) with a reference image. For other content types or custom layouts with reference images, use the general generate_image tool instead.

Args: reference_image: Reference image - must be either a file path (e.g., "/path/to/image.jpg") or base64 encoded image data. Claude's "[Image #1]" format is not supported - save the image to a file first. main_text: Main headline text for the thumbnail secondary_text: Optional secondary text for the red banner topic: Topic or subject matter (e.g., 'tech side hustles', 'AWS certification') style_override: Optional style override for different thumbnail types creative_mode: Enable creative freedom vs. consistent branding (default: False) composition_style: Composition approach (centered, left, right, dynamic, creative) layout_freedom: Layout constraints (standard=branding, flexible=some creativity, experimental=full freedom)

ParametersJSON Schema
NameRequiredDescriptionDefault
topicNo
main_textYes
creative_modeNo
layout_freedomNostandard
secondary_textNo
style_overrideNo
reference_imageYes
composition_styleNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

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

The description discloses a key behavioral constraint: reference_image cannot use Claude's '[Image #1]' format and must be a file path or base64 data. It also explains the meaning of layout_freedom values (standard, flexible, experimental), adding value beyond the annotations (which are absent).

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 structured with a bolded intro, usage guidance, and an args list. Each arg line is compact yet informative, with no filler. The length is justified by the tool's eight parameters.

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?

Given the tool's complexity (8 parameters, no schema descriptions, no annotations), this description covers purpose, usage, parameter semantics, and constraints. The existence of an output schema means return values need not be explained, so no gaps are apparent.

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

Parameters5/5

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

With 0% schema description coverage, the description compensates by explaining all 8 parameters. For example, it clarifies that reference_image must be a file path or base64, and that layout_freedom maps to branding constraints. It provides examples for topic and lists options for composition_style.

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 identifies the tool as a specialized YouTube thumbnail generator using reference images and predefined layouts, and it distinguishes itself from the general generate_image tool by mentioning the standard thumbnail layout. The 'person on right, text on left, red banner' detail provides concrete context.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool (for YouTube thumbnails with the standard layout) and when to use generate_image instead (other content types or custom layouts), giving clear decision criteria.

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

get_prompt_suggestionsB

Get suggestions for improving image generation prompts.

Args: content_type: Type of content (youtube_thumbnail, blog_header, blog_featured, social_media, general) current_prompt: Current prompt to analyze and improve (optional)

ParametersJSON Schema
NameRequiredDescriptionDefault
content_typeYes
current_promptNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior1/5

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. However, it only states the purpose and parameters, with no mention of side effects, permissions, rate limits, or whether the operation is read-only.

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 concise and front-loaded with the primary purpose. The parameter list is compact and directly useful, with no redundant or extraneous information.

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?

Although the output schema exists (covering return values), the description lacks usage guidelines and behavioral transparency. For a simple tool, this is an acceptable but incomplete context, as an agent needs guidance on when and how to invoke it safely.

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 description adds valuable meaning beyond the schema by listing the allowed values for content_type and clarifying that current_prompt is optional. Since schema description coverage is 0%, this compensation is important and reasonably detailed.

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 function with a specific verb ('Get') and resource ('suggestions for improving image generation prompts'). It is easily distinguishable from sibling tools like generate_image or analyze_thumbnail, which have different purposes.

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 is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or scenarios where this tool is preferred.

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

optimize_for_platformA

Optimize an existing image for a specific platform.

Args: image_data: Base64 encoded image data target_platform: Target platform (youtube, instagram, twitter, facebook, blog) content_type: Type of content (e.g., tutorial, entertainment, news) optimization_focus: Areas to focus optimization on

ParametersJSON Schema
NameRequiredDescriptionDefault
image_dataYes
content_typeNo
target_platformYes
optimization_focusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does not mention whether the original image is modified, if the operation is destructive, any authentication needs, rate limits, or what the output contains. This is a significant gap for a tool that processes user-provided data.

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 concise: one sentence stating the purpose followed by a structured list of parameters. No filler or redundant information. The purpose is front-loaded, and each parameter gets a brief, informative explanation.

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 4 parameters and 0% schema coverage, the description covers each parameter and the core purpose effectively. The presence of an output schema means return values need not be explained here. However, it lacks any behavioral context such as preconditions or error handling, leaving some gaps for a tool in this complexity range.

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 'Args' section in the description explicitly defines each parameter: image_data as Base64 encoded, target_platform with allowed examples, content_type with example values, and optimization_focus as 'areas to focus optimization on'. This compensates for the schema's 0% description coverage and provides meaningful meaning beyond the raw property names.

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 'Optimize an existing image for a specific platform' with a specific verb (optimize), resource (existing image), and scope (platform). This distinguishes it from sibling tools like generate_image (creating new images) and analyze_thumbnail (analyzing).

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 mention of 'existing image' and listing target platforms (youtube, instagram, twitter, facebook, blog) provides clear context for when to use this tool. However, it does not explicitly state alternatives or exclusions, so it doesn't fully satisfy the 'when not to use' guidance.

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.

  1. 7 tool updatesv0.1.1
    • First observedanalyze_thumbnail
    • First observedcleanup_temp_files
    • First observedgenerate_batch
    • First observedgenerate_image
    • First observedgenerate_reference_thumbnail
    • First observedget_prompt_suggestions
    • First observedoptimize_for_platform
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

The tools are mostly distinct, but generate_image and generate_reference_thumbnail overlap in functionality; however, the descriptions clearly direct agents to the specialized tool for reference thumbnails. generate_batch is a batch wrapper but is clearly named and doesn't conflict semantically.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, such as generate_image, optimize_for_platform, analyze_thumbnail, and cleanup_temp_files. This makes the tool set predictable and easy to navigate.

Tool Count5/5

Seven tools cover generation, batch processing, optimization, analysis, prompt suggestions, and maintenance without being excessive or too sparse. The count is well-scoped for an image generation server.

Completeness4/5

The tool surface covers image generation, batch creation, platform optimization, thumbnail analysis, and prompt improvement. A minor gap is the lack of an image editing or retrieval tool, but the core workflow is well-covered and no critical dead ends are present.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Image MCP Server

    iplanwebsites
    A
    license
    C
    quality
    C
    maintenance
    An MCP server that provides AI image generation capabilities using OpenAI and Replicate APIs with support for customizable prompts and dimensions. It features specialized tools for generating square, landscape, and portrait images through simple natural language commands.
    5
    26 npm
    MIT

  • openai-images-mcp

    sam-david
    F
    license
    A
    quality
    D
    maintenance
    An MCP server for generating and editing images using OpenAI's GPT Image and DALL·E models. It provides tools for image generation, editing, variation creation, and model listing with support for multiple AI models.
    4
    -