Image-Refinery is a high-performance Model Context Protocol (MCP) server written in Rust, designed for advanced image processing, metadata reconstruction, and asset optimization. By leveraging the speed and safety of Rust, it provides a robust toolkit for developers to automate complex visual workflows—from content-aware cropping and background removal to comprehensive EXIF metadata management.

Key Features

• Geometric Transformations: Perform precise resizing, cropping, rotation, and flipping with high fidelity.
• Smart Crop: Utilize content-aware algorithms to automatically identify and preserve visual focal points during cropping.
• Visual Filters: Apply professional-grade filters including blur, sharpen, grayscale, brightness/contrast adjustments, and rounded corners.
• Format Transcoding: Seamlessly convert between modern formats like PNG, JPG, WebP, and AVIF.
• Asset Optimization: Significantly reduce file sizes through intelligent lossy and lossless compression techniques.
• Layer Compositing: Overlay multiple images or text layers with granular control over positioning and blend modes.
• Background Removal: Extract subjects to generate transparent PNG or WebP files, ideal for e-commerce and icon design.
• Icon Generation: Automate the creation of multi-size App icon sets and multi-layer .ico files.
• Metadata Reconstruction: Purge sensitive data (EXIF, GPS) via pixel-level re-encoding or inject custom tags like Copyright and Artist.
• Robust Format Detection: Intelligent byte-level inspection to handle mismatched file extensions (e.g., JPEG data inside a .png file).

Supported Environments

Image-Refinery is compatible with any MCP-enabled environment, including:

• IDE & Editors: Cursor, Windsurf, Zed, Antigravity.
• AI Agents: Roo Code, Cline, Augment Code.
• Desktop Applications: Claude Desktop.

Tool Reference

1. analyze_image

Extracts comprehensive technical metadata from image files.

• Functions: Detects dimensions (width/height), file format, color space, and existing EXIF data.
• Inputs: image_path (supports glob patterns like *.jpg).
• Output: A detailed JSON object containing technical specifications.

2. transform_image

Executes primary geometric transformations.

• Functions: General-purpose resizing, cropping, and orientation adjustments.
• Options: Includes smart_crop for automated framing.
• Parameters: image_path, width, height, rotate, flip, flop, quality (integer 1-100).

3. resize_image

A streamlined tool dedicated to scaling.

• Functions: Adjusts dimensions while maintaining aspect ratio automatically if only one dimension is provided.
• Parameters: image_path, width, height, quality.

4. stylize_image

Applies visual enhancements and stylistic filters.

• Functions: blur, sharpen, grayscale, brightness, contrast, and rounded_corners.
• Parameters: image_path, and corresponding adjustment values for each filter.

5. convert_format

Transcodes images to different file types.

• Functions: Converts to PNG, JPG, WebP, or AVIF.
• Parameters: image_path, format (target), quality.
• Note: The resulting file is re-encoded, which strips original metadata by default for privacy.

6. optimize_image

Focuses on storage efficiency.

• Functions: Minimizes file footprint without altering dimensions.
• Parameters: image_path, quality (1-100) or lossless (boolean).

7. composite_image

Handles multi-layer visual construction.

• Functions: Overlays watermarks, logos, or captions onto a base image.
• Parameters: image_path (base), overlays array (containing path or text, x/y coordinates, font_size, and color).

8. remove_background

Automated subject extraction.

• Functions: Generates an alpha channel to remove backgrounds.
• Parameters: image_path, force_color (hex), sensitivity (low/medium/high), format ("png" or "webp").

9. generate_icons

Development utility for application assets.

• Functions: Produces a standardized set of PNG icons and an optional .ico bundle.
• Parameters: image_path, sizes (array of integers), generate_ico (boolean).

10. set_metadata

Manages image-level documentation (EXIF).

• Mode: Overwrite-only. Existing metadata is replaced with the provided tags.
• Supported Tags: Copyright, Artist, Software, Description, UserComment, Make, Model.
• Supported Formats: JPG, PNG, WebP.
• Parameters: image_path, tags (key-value object).

Configuration

To integrate Image-Refinery into your MCP workflow, add the following configuration to your settings file:

{
  "mcpServers": {
    "image-refinery": {
      "command": "npx",
      "args": ["-y", "@datafrog-io/image-refinery"],
      "env": {
        "IMAGE_REFINERY_API_KEY": "YOUR_LICENSE_KEY"
      }
    }
  }
}