Enhanced Image Analysis MCP Server

A powerful Model Context Protocol (MCP) server that uses advanced heuristics to analyze images and generate intelligent, descriptive filenames. Perfect for organizing large photo collections, screenshots, and digital assets.

🚀 Features

🎯 Smart Image Analysis: Advanced heuristic analysis of image characteristics
📝 Intelligent Naming: Four naming styles (descriptive, technical, artistic, location)
📂 Batch Processing: Analyze entire directories with recursive search
🎨 Color Analysis: Dominant color detection and classification
📊 EXIF Data: Extract camera settings, timestamps, and metadata
📁 Auto Organization: Sort images into folders by content, date, size, or format
🔍 Comprehensive Metadata: Extract detailed technical information
⚡ Smart Caching: Avoid re-analyzing unchanged images

📦 Installation

Quick Setup

cd /Users/anthonyturner/MCPs/image-analysis-server
chmod +x setup.sh
./setup.sh

Manual Installation

# Install dependencies
pip3 install mcp Pillow

# Make executable
chmod +x enhanced_image_analysis_server.py

⚙️ Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "image-analysis": {
      "command": "python3",
      "args": ["/Users/anthonyturner/MCPs/image-analysis-server/enhanced_image_analysis_server.py"],
      "env": {}
    }
  }
}

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

🛠️ Available Tools

1. `ai_analyze_directory_images`

Analyze all images in a directory and generate intelligent names.

Parameters:

directory_path (required): Path to directory containing images
recursive (optional): Search subdirectories (default: false)
rename_files (optional): Actually rename files (default: false)
prefix (optional): Add prefix to generated names
naming_style (optional): Style of naming (default: "descriptive")

Example Usage:

Analyze all images in ~/Pictures/vacation2024 and suggest better names using technical style

2. `ai_analyze_single_image`

Analyze a single image file and generate a descriptive name.

Parameters:

image_path (required): Path to the image file
naming_style (optional): Naming style (default: "descriptive")
detailed_analysis (optional): Provide comprehensive analysis (default: false)

Example Usage:

Analyze /Users/me/Desktop/photo.jpg with detailed analysis using artistic naming style

3. `extract_comprehensive_metadata`

Extract detailed metadata including EXIF data and color analysis.

Parameters:

image_path (required): Path to the image file
include_color_analysis (optional): Include color palette analysis (default: true)

Example Usage:

Extract comprehensive metadata from my screenshot including color analysis

4. `organize_images_by_content`

Organize images into folders based on detected content and characteristics.

Parameters:

directory_path (required): Path to directory containing images
create_folders (optional): Actually create folders and move files (default: false)
organization_method (optional): Method to organize (default: "content")

Organization Methods:

content: By detected content (screenshots, photos, portraits, etc.)
date: By creation date (YYYY-MM format)
size: By image resolution (small, medium, large, huge)
format: By file format (jpg, png, gif, etc.)

🎨 Naming Styles

Descriptive (Default)

Focuses on visual content and characteristics:

red_landscape_photo.jpg
blue_portrait_screenshot.png

Technical

Emphasizes technical specifications:

large_res_landscape_camera.jpg
medium_res_portrait_screenshot.png

Artistic

Highlights aesthetic qualities:

red_bright_photo.jpg
gray_dark_bw.png

Location

Designed for organizing by context:

dated_landscape.jpg
photo_portrait.png

📊 Smart Analysis Features

Color Analysis

Dominant Colors: Top 5 colors with percentages
Color Family: Classification (red, blue, green, etc.)
Grayscale Detection: Identifies black & white images
Brightness Analysis: Average brightness calculation

Content Detection

The server analyzes filename patterns to detect:

Screenshots: Screen captures and UI elements
Photos: Camera-taken images and photography
Edited Images: Modified or processed images
Scans: Digitized documents
Logos/Icons: Brand and graphic elements

EXIF Data Extraction

Camera Information: Make, model, settings
Timestamps: When photo was taken
Software: Editing applications used
GPS Data: Location information (when available)

🚀 Example Workflows

Organize Downloads Folder

I have a messy Downloads folder with hundreds of images. Can you organize them by content type and suggest better names?

Rename Vacation Photos

Analyze images in ~/Pictures/Hawaii2024 recursively, use descriptive naming with prefix "hawaii", and actually rename the files

Technical Analysis

Extract comprehensive metadata from ~/Desktop/camera_test.jpg including color analysis and EXIF data

Batch Screenshot Organization

Organize all images in ~/Desktop by content, actually create the folders and move files

🔧 Advanced Features

Intelligent Conflict Resolution

Automatically handles duplicate filenames
Adds incremental counters when needed
Preserves original files during preview mode

Performance Optimizations

Smart Caching: Avoids re-analyzing unchanged images
Efficient Color Analysis: Uses image thumbnails for color detection
Batch Processing: Optimized for large directories

Error Handling

Graceful Degradation: Continues processing other files if one fails
Detailed Error Reports: Clear error messages for troubleshooting
File Validation: Ensures only supported formats are processed

📋 Supported Formats

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
BMP (.bmp)
TIFF (.tiff)
WebP (.webp)

🛡️ Safety Features

Preview Mode: Default behavior suggests changes without applying them
Backup Consideration: Always backup important files before batch operations
Permission Checks: Validates file system permissions before operations
Non-destructive Analysis: Metadata extraction never modifies original files

🚨 Troubleshooting

Common Issues

"No image files found"
- Verify directory path is correct
- Check if images are in supported formats
- Try recursive search for images in subdirectories
"Permission denied"
- Ensure read/write permissions on target directory
- Check if files are not locked by other applications
"Failed to analyze image"
- File may be corrupted or not a valid image
- Check if sufficient disk space is available

Debug Mode

# Run with debug logging
python3 enhanced_image_analysis_server.py --debug

🔮 Future Enhancements

The server is designed to be easily extensible:

AI Vision Integration: Add OpenAI GPT-4 Vision or Google Cloud Vision
Face Detection: Identify and organize photos with people
Object Recognition: Detect specific objects, animals, or scenes
Duplicate Detection: Find and organize duplicate images
Cloud Storage: Support for Google Photos, iCloud, etc.

📄 License

MIT License - Feel free to modify and distribute.

🤝 Contributing

Contributions welcome! Areas for improvement:

Additional naming styles
More sophisticated content detection
Integration with cloud vision APIs
Performance optimizations
Additional metadata extraction

Ready to organize your images intelligently? Install the Enhanced Image Analysis MCP Server and transform your photo management workflow!