2squirrelsai/local-mcp-image-analysis-server

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

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

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