AI Image MCP Server

# AI Image MCP Server A comprehensive Model Context Protocol (MCP) server that provides both **AI-powered image analysis** and **AI image generation** capabilities using OpenAI's Vision API and image generation models. ## System Requirements **Tested on:** - macOS 14.3.0 (Darwin 23.3.0, ARM64) - Python 3.13.0 - uv 0.7.13 - OpenAI API access ## Features ### 🔍 Image Analysis & Description - **Smart Image Analysis**: Analyze images using OpenAI's GPT-4O Vision model - **Targeted Analysis**: Analyze specific aspects (objects, text, colors, composition, emotions) - **Image Comparisons**: Compare two images and highlight similarities/differences - **Metadata Extraction**: Get technical information about image files - **Intelligent Caching**: Cache analysis results to avoid repeated API calls - **Multiple Formats**: Support for PNG, JPEG, GIF, and WebP formats ### 🎨 Image Generation & Editing - **Text-to-Image Generation**: Create images from text prompts using DALL-E 2, DALL-E 3, or GPT-Image-1 - **Image Editing**: Edit existing images with text prompts using GPT-Image-1 or DALL-E 2 - **Image Variations**: Create variations of existing images using DALL-E 2 - **Flexible Output**: Save generated images locally with custom naming and directories - **Model Support**: Full support for all OpenAI image generation models with their specific features ## MCP Tools 1. `describe_image(image_path, prompt)` - Get detailed image descriptions 2. `analyze_image_content(image_path, analysis_type)` - Analyze specific aspects 3. `compare_images(image1_path, image2_path, comparison_focus)` - Compare two images 4. `get_image_metadata(image_path)` - Extract technical metadata 5. `get_cache_info()` - View cache statistics 6. `clear_image_cache()` - Clear cached results ## Installation 1. Install dependencies: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh uv add mcp[cli] openai pillow requests ``` 2. Set your OpenAI API key: ```bash export OPENAI_API_KEY="your-api-key-here" ``` 3. Run the server: ```bash uv run main.py ``` ## Running the Server ```bash uv run main.py ``` ## MCP Integration ### Claude Desktop ```json { "mcpServers": { "ai-image-mcp": { "command": "uv", "args": [ "--directory", "/absolute/path/to/ai-image-mcp", "run", "main.py" ], "env": { "OPENAI_API_KEY": "your-api-key-here" } } } } ``` ### Cursor Configure MCP in Cursor settings: ```json { "servers": { "ai-image-mcp": { "command": "uv", "args": ["run", "main.py"], "cwd": "/absolute/path/to/ai-image-mcp", "env": { "OPENAI_API_KEY": "your-api-key-here" } } } } ``` ## Analysis Types - `general`: Overall image description - `objects`: Object detection and identification - `text`: Text extraction and OCR - `colors`: Color analysis and palette - `composition`: Visual composition and layout - `emotions`: Emotional content and mood ## Project Structure ``` ai-image-mcp/ ├── test_data/ # Sample images (gitignored) ├── tools/ # MCP tool definitions ├── utils/ # Utilities (caching, OpenAI client) ├── main.py # Server entry point └── server.py # MCP server instance ``` ## Caching - Automatic file change detection via SHA-256 hashes - 30-day cache expiration - Separate cache entries for different prompts/analysis types - Significant performance improvements (1000x+ faster than API calls) ## Available Tools ### Image Analysis Tools #### `describe_image` Analyze an image and provide a detailed description. - **Parameters**: - `image_path` (str): Path to the image file - `prompt` (str, optional): Custom analysis prompt - **Supports**: PNG, JPEG, GIF, WebP - **Features**: Caching, file validation, comprehensive error handling #### `analyze_image_content` Perform targeted analysis of specific image aspects. - **Parameters**: - `image_path` (str): Path to the image file - `analysis_type` (str): Type of analysis - "general", "objects", "text", "colors", "composition", "emotions" - **Features**: Specialized prompts for different analysis types #### `compare_images` Compare two images and highlight similarities and differences. - **Parameters**: - `image1_path` (str): Path to first image - `image2_path` (str): Path to second image - `comparison_focus` (str): What to focus on in comparison #### `get_image_metadata` Get technical metadata about an image file. - **Returns**: File size, dimensions, format, color mode, aspect ratio, etc. ### Image Generation Tools #### `generate_image` Generate images from text prompts using OpenAI's image generation models. - **Parameters**: - `prompt` (str): Text description of desired image - `model` (str): "dall-e-2", "dall-e-3", or "gpt-image-1" (default: dall-e-3) - `size` (str, optional): Image dimensions (varies by model) - `quality` (str, optional): Quality setting (varies by model) - `style` (str, optional): "vivid" or "natural" (DALL-E 3 only) - `n` (int, optional): Number of images (1-10, DALL-E 3 only supports 1) - `output_dir` (str): Directory to save images (default: "./generated_images") - `filename_prefix` (str): Prefix for filenames (default: "generated") **Model-Specific Features**: - **DALL-E 2**: Basic generation, sizes: 256x256, 512x512, 1024x1024 - **DALL-E 3**: High quality, styles (vivid/natural), sizes: 1024x1024, 1792x1024, 1024x1792 - **GPT-Image-1**: Advanced features, transparency support, compression control #### `edit_image` Edit existing images using text prompts. - **Parameters**: - `image_path` (str): Path to image to edit - `prompt` (str): Description of desired edit - `mask_path` (str, optional): Path to mask image (PNG with transparent edit areas) - `model` (str): "gpt-image-1" or "dall-e-2" (default: gpt-image-1) - `size`, `quality`, `n`: Model-specific options - `output_dir`, `filename_prefix`: Output configuration **Supported Models**: GPT-Image-1 (up to 16 images, 50MB each) and DALL-E 2 (1 square PNG, 4MB max) #### `create_image_variations` Create variations of existing images using DALL-E 2. - **Parameters**: - `image_path` (str): Path to source image (must be square PNG, <4MB) - `n` (int): Number of variations (1-10, default: 2) - `size` (str): Variation size - "256x256", "512x512", "1024x1024" - `output_dir`, `filename_prefix`: Output configuration #### `list_generated_images` List all generated images in a directory with metadata. - **Parameters**: - `directory` (str): Directory to scan (default: "./generated_images") - **Returns**: File listing with sizes, dimensions, modification dates ### Cache Management Tools #### `get_cache_info` Get information about the analysis cache (file count, size, location). #### `clear_image_cache` Clear all cached analysis results. ## Model Comparison | Feature | DALL-E 2 | DALL-E 3 | GPT-Image-1 | |---------|----------|----------|-------------| | **Generation** | ✅ Basic | ✅ High Quality | ✅ Advanced | | **Editing** | ✅ Limited | ❌ | ✅ Advanced | | **Variations** | ✅ | ❌ | ❌ | | **Max Images** | 10 | 1 | 10 | | **Sizes** | 256x256, 512x512, 1024x1024 | 1024x1024, 1792x1024, 1024x1792 | 1024x1024, 1536x1024, 1024x1536 | | **Styles** | ❌ | vivid, natural | ❌ | | **Quality** | standard | standard, hd | auto, high, medium, low | | **Transparency** | ❌ | ❌ | ✅ | | **Max Prompt** | 1000 chars | 4000 chars | 32000 chars | ## Usage Examples ### Generate a Basic Image ```python # Generate an image with DALL-E 3 generate_image( prompt="A serene mountain landscape at sunset with a crystal clear lake", model="dall-e-3", size="1792x1024", quality="hd", style="natural" ) ``` ### Edit an Existing Image ```python # Add elements to an image edit_image( image_path="./photos/room.png", prompt="Add a beautiful bookshelf filled with colorful books to the left wall", model="gpt-image-1", quality="high" ) ``` ### Create Image Variations ```python # Create variations of a logo create_image_variations( image_path="./logos/logo.png", n=5, size="1024x1024" ) ``` ### Analyze Generated Images ```python # Analyze a generated image describe_image( image_path="./generated_images/generated_1234567890_1.png", prompt="Describe the artistic style and composition of this generated image" ) ``` ## File Organization Generated images are automatically organized in separate directories: - `./generated_images/` - Text-to-image generations - `./edited_images/` - Image edits - `./image_variations/` - Image variations Files are named with timestamps to avoid conflicts: - `generated_1234567890_1.png` - `edited_1234567890_1.png` - `variation_1234567890_1.png` ## Error Handling The server includes comprehensive error handling for: - Invalid image formats and file paths - Model-specific parameter validation - File size and dimension limits - API quota and rate limiting - Network connectivity issues - Malformed prompts and parameters ## Cache System The analysis tools use an intelligent caching system: - **File Change Detection**: Uses SHA-256 hashes to detect file changes - **30-Day Expiration**: Automatically expires old cache entries - **Safe Operation**: Cache failures don't affect main functionality - **Efficient Storage**: Uses MD5 hashes for safe cache key generation ## Requirements - Python 3.13+ - OpenAI API key with access to Vision API and Image Generation - Required packages: `mcp[cli]>=1.9.4`, `openai>=1.90.0`, `pillow>=11.2.1`, `requests>=2.32.4` ## License This project is licensed under the MIT License - see the LICENSE file for details.