jfdasher/image-processing-mcp

Image Processing MCP Server

A Model Context Protocol (MCP) server providing comprehensive image analysis and manipulation capabilities for professional photography post-processing workflows.

Features

• Image Analysis: Comprehensive tonal, color, and spatial analysis
• Style Transfer: Compare images and generate Lightroom-compatible recipes
• Semantic Masking: FastSAM-powered segmentation for selective adjustments
• Professional Tools: Exposure, color, curves, sharpening, and more
• Batch Processing: Apply recipes to multiple images efficiently
• RAW Support: Process CR2, NEF, ARW, and other RAW formats

Installation

# Clone the repository
git clone https://github.com/jdasher/image-processing-mcp.git
cd image-processing-mcp

# Install with pip
pip install -e .

# Or with dev dependencies
pip install -e ".[dev]"

# Models will download automatically on first use
# Or download manually:
python scripts/download_models.py

Configuration

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

{
  "mcpServers": {
    "image-processing": {
      "command": "python",
      "args": ["-m", "image_processing_mcp"],
      "env": {
        "IMAGE_CACHE_DIR": "/tmp/image_mcp_cache",
        "MAX_MEMORY_MB": "600"
      }
    }
  }
}

Environment Variables

• IMAGE_CACHE_DIR: Temporary files location (default: /tmp/image_mcp_cache)
• MAX_MEMORY_MB: Session memory cap (default: 600)
• FASTSAM_MODEL_PATH: Path to FastSAM model (auto-downloads if not found)
• ENABLE_GPU: Enable GPU acceleration (default: auto-detect)

Quick Start

Basic Analysis

# Load and analyze an image
load_image(path="photo.jpg", image_id="main")
analysis = analyze_image(image_id="main")

# Review histogram, tonal analysis, color properties
print(analysis['tonal_analysis'])

Style Transfer

# Compare two images and generate recipe
load_image(path="source.cr2", image_id="source")
load_image(path="target.jpg", image_id="target")

comparison = compare_images(
    source_id="source",
    target_id="target",
    generate_recipe=True
)

# Apply recipe to source
apply_recipe(
    input_path="source.cr2",
    output_path="styled.jpg",
    recipe=comparison['recipe']
)

Selective Adjustments

# Segment image and select regions
load_image(path="photo.jpg", image_id="img")
segments = segment_everything(image_id="img")

# Combine masks for specific region
select_masks(image_id="img", mask_ids=[1, 2, 3], name="subject")

# Apply adjustment to masked area only
apply_selective_adjustment(
    input_path="photo.jpg",
    output_path="adjusted.jpg",
    mask_source_image_id="img",
    mask_name="subject",
    adjustment={"type": "exposure", "stops": 0.5}
)

Available Tools

Analysis Tools (Stateful)

• load_image - Load image into session
• analyze_image - Comprehensive analysis
• compare_images - Differential analysis for style transfer
• generate_recipe - Generate Lightroom-compatible recipe
• segment_everything - Semantic segmentation with FastSAM
• select_masks - Combine multiple masks
• invert_mask - Invert mask selection
• get_histogram - Retrieve histogram data
• unload_image - Free memory

Modification Tools (Stateless)

• adjust_exposure - Brightness adjustment
• adjust_color - White balance, saturation, vibrance
• apply_curves - Tonal curve application
• apply_sharpening - Unsharp mask
• apply_recipe - Full recipe application
• apply_selective_adjustment - Masked adjustments
• batch_process - Batch processing with recipes

Testing

# Run all tests
pytest

# With coverage report
pytest --cov=image_processing_mcp --cov-report=html

# Run specific test
pytest tests/test_analysis.py

Performance

Target metrics (50MP images):

• Image loading: <2s (JPEG), <5s (RAW)
• Analysis: <3s
• Segmentation: <10s (CPU), <3s (GPU)
• Recipe application: <5s
• Memory footprint: <700MB (4 images loaded)

License

MIT License - See LICENSE file for details

Authors

• Jim Dasher
• Claude (AI Assistant)

Version

1.0.0 - October 2025