Image Analysis MCP Server

A comprehensive read-only image analysis MCP (Model Context Protocol) server that provides Claude with detailed image inspection capabilities.

Features

• Metadata & EXIF Extraction: Camera settings, GPS, timestamps, and more
• Histogram Analysis: RGB and luminance histograms with statistics
• Tonal Analysis: Shadows, midtones, highlights, dynamic range, and clipping detection
• Color Analysis: Dominant colors, color temperature, saturation, and color cast detection
• Spatial Properties: Sharpness scoring, noise estimation, edge density, and blur detection
• Frequency Analysis: FFT-based detail level assessment (optional)
• Preview Generation: Base64-encoded preview images (optional)

Supported Formats

Standard Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• TIFF (.tif, .tiff)
• WebP (.webp)

RAW Formats

• Canon RAW (.cr2, .cr3)
• Nikon RAW (.nef)
• Sony RAW (.arw)
• Adobe DNG (.dng)
• Fuji RAW (.raf)
• Olympus RAW (.orf)

Installation

Option 1: Docker (Recommended)

The easiest way to get started - no Python setup required!

# Build the Docker image
cd image_analysis
docker build -t image-analysis-mcp:latest .

# Test it works
docker run --rm image-analysis-mcp:latest python -c "import image_analysis_mcp; print('✓ OK')"

See DOCKER.md for complete Docker documentation.

Option 2: Poetry

# Prerequisites: Python 3.12+, Poetry
cd image_analysis

# Install dependencies
poetry install

# Activate the virtual environment
poetry shell

Option 3: pip

# Prerequisites: Python 3.12+
cd image_analysis

# Install the package
pip install -e .

Usage

Running the MCP Server

The server can be run directly:

# Using Poetry
poetry run image-analysis-mcp

# Or if in activated virtual environment
image-analysis-mcp

Configuration for Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

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

Using Docker (Recommended)

{
  "mcpServers": {
    "image-analysis": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/images:/images:ro",
        "image-analysis-mcp:latest"
      ]
    }
  }
}

Then reference images as /images/photo.jpg in Claude.

Using Poetry

{
  "mcpServers": {
    "image-analysis": {
      "command": "poetry",
      "args": ["run", "image-analysis-mcp"],
      "cwd": "/absolute/path/to/image_analysis"
    }
  }
}

Using pip (Global Install)

{
  "mcpServers": {
    "image-analysis": {
      "command": "image-analysis-mcp"
    }
  }
}

Available Tools

1. get_metadata

Fast metadata and EXIF extraction without loading full image data.

Parameters:

• filepath (str): Path to image file

Example:

What camera was used for IMG_1234.CR2?

2. get_histogram

Extract RGB and luminance histograms with channel statistics.

Parameters:

• filepath (str): Path to image file
• process_raw (bool, optional): Process RAW files (default: True)

Example:

Show me the histogram for landscape.jpg

3. analyze_image

Comprehensive image analysis including all properties.

Parameters:

• filepath (str): Path to image file
• include_frequency (bool, optional): Include FFT analysis (default: False)
• include_preview (bool, optional): Generate preview image (default: False)
• preview_max_dimension (int, optional): Preview max size (default: 1920)
• preview_format (str, optional): "JPEG", "PNG", or "WEBP" (default: "JPEG")
• preview_quality (int, optional): Quality 1-100 (default: 85)
• process_raw (bool, optional): Process RAW files (default: True)

Example:

Analyze photo.jpg and tell me if it's sharp enough for printing

Analyze this RAW file and show me a preview

Architecture

This server follows a fully stateless architecture:

• Each tool call is independent
• Images are loaded, analyzed, and immediately discarded
• No caching or session state
• Predictable and reproducible results

Performance

Typical performance on modern hardware:

Operation	2MP Image	12MP Image	50MP Image
get_metadata	10ms	15ms	25ms
get_histogram	50ms	150ms	600ms
analyze_image	200ms	800ms	3000ms
analyze_image (with preview)	300ms	1100ms	4000ms
analyze_image (with FFT)	500ms	2000ms	8000ms

Example Conversations

Check Image Quality

User: Is wedding_photo.jpg sharp enough for a large print?
Claude: [Uses analyze_image to check sharpness, noise, and resolution]

Exposure Analysis

User: Is this sunset photo overexposed?
Claude: [Uses analyze_image to check histogram and clipping]

Color Analysis

User: What are the dominant colors in this landscape?
Claude: [Uses analyze_image to extract dominant colors and temperature]

Metadata Extraction

User: What camera settings were used for IMG_5678.NEF?
Claude: [Uses get_metadata to extract EXIF data]

Error Handling

The server provides clear error messages:

• FILE_NOT_FOUND: File doesn't exist
• PERMISSION_DENIED: Cannot read file
• UNSUPPORTED_FORMAT: Format not supported
• CORRUPTED_FILE: File is corrupted
• OUT_OF_MEMORY: Image too large
• INVALID_PARAMETER: Bad parameter value
• RAW_PROCESSING_FAILED: RAW conversion failed

Development

Running Tests

poetry run pytest

Code Formatting

poetry run black src/

Type Checking

poetry run mypy src/

License

This project is provided as-is for use with Claude Desktop and MCP.

Author

Jim Dasher

Version

1.0.0 - October 28, 2025