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)

Related MCP server: Image Description MCP Server

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:

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