Unified ImageSorcery Adapter

Connect Claude Code to ImageSorcery for automated image processing, format conversion, resizing, and optimization through the Model Context Protocol.

When to Use This MCP Server

Connect this server when you need to:

• Process, resize, and optimize images as part of your development workflow without leaving Claude Code to use separate image editing software
• Batch convert images between formats (PNG, JPEG, WebP, AVIF) with quality and compression controls for web asset preparation
• Generate responsive image variants, thumbnails, and optimized versions for different screen sizes and device capabilities

Consider alternatives when:

• You need complex image editing with layers, masks, or artistic effects, which require full image editing software like Photoshop or GIMP
• Your image processing is part of a build pipeline that already uses Sharp, ImageMagick, or similar tools integrated into your bundler

Quick Start

Configuration

Copy
name: unified-imagesorcery-adapter
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect unified-imagesorcery-adapter

Available Tools

resize:            Resize images to specified dimensions with aspect ratio preservation options
convert:           Convert images between formats with quality and compression settings
optimize:          Optimize image file size while maintaining visual quality thresholds
thumbnail:         Generate thumbnail variants at predefined or custom dimensions
batch-process:     Process multiple images with the same transformation pipeline

Core Concepts

ImageSorcery MCP Server Overview

Aspect	Details
Transport	stdio-based MCP server with local image processing capabilities
Processing	Server-side image manipulation using optimized native image libraries
Formats	PNG, JPEG, WebP, AVIF, TIFF, GIF, and SVG rasterization support
Optimization	Lossy and lossless compression with configurable quality thresholds
Batch Support	Process multiple images with consistent transformation settings

ImageSorcery Processing Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [ImageSorcery MCP Server]
                              |
                              v
                     [Image Processing Engine]
                      /       |        \
                Resize     Convert    Optimize
                Engine     Engine     Engine
                      \       |        /
                    [Native Image Libraries]
                              |
                              v
                     [Output File System]
                   Processed | Optimized | Thumbnails

Configuration

Parameter	Type	Default	Description
output_dir	string	./processed	Default output directory for processed images
default_quality	integer	85	Default JPEG/WebP quality level (1-100) for compression
preserve_metadata	boolean	false	Preserve EXIF and other metadata in processed images
max_dimension	integer	4096	Maximum allowed width or height in pixels for output images
default_format	string	original	Default output format; "original" preserves input format

Best Practices

1. Use WebP for Web Assets - Convert images to WebP format for web deployment. WebP provides 25-35% smaller file sizes compared to JPEG at equivalent visual quality, reducing page load times significantly.

2. Generate Multiple Responsive Sizes - Use batch-process to create responsive image variants (320w, 640w, 1024w, 1920w) from a single source image. This enables responsive image loading with srcset attributes in your HTML.

3. Optimize Before Committing to Git - Run optimize on all image assets before adding them to version control. Unoptimized images bloat repository size and slow down cloning, especially for projects with many visual assets.

4. Strip Metadata for Privacy - Set preserve_metadata to false when processing images for public deployment. EXIF metadata can contain GPS coordinates, camera information, and other data that should not be publicly exposed.

5. Use Lossless Formats for Source Assets - Keep original source images in PNG or TIFF format and only convert to lossy formats (JPEG, WebP) for deployment. This preserves maximum quality for future re-processing if requirements change.

Common Issues

1. Output Quality Lower Than Expected - Increase default_quality above 85 for images where visual fidelity is critical. The default quality level prioritizes file size reduction, which may not suit high-quality photography or detailed graphics.

2. Resize Distorts Image Aspect Ratio - Ensure the resize operation preserves aspect ratio by specifying only width or only height, not both. When both dimensions are specified, use a fit mode (contain, cover, fill) to control how aspect ratio is handled.

3. AVIF Conversion Fails or Is Slow - AVIF encoding is computationally intensive and may not be supported on all platforms. Fall back to WebP for broad compatibility, or increase the processing timeout for AVIF conversions.