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

Manual Installation

⚙️ Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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:

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:

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:

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

Rename Vacation Photos

Technical Analysis

Batch Screenshot Organization

🔧 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

1. "No image files found"

   • Verify directory path is correct

   • Check if images are in supported formats

   • Try recursive search for images in subdirectories

2. "Permission denied"

   • Ensure read/write permissions on target directory

   • Check if files are not locked by other applications

3. "Failed to analyze image"

   • File may be corrupted or not a valid image

   • Check if sufficient disk space is available

Debug Mode

🔮 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!