MCP Image Optimizer

A Model Context Protocol server for image optimization. Process images from URLs or local files with advanced transformations powered by Sharp.

Features

• 🖼️ Process images from URLs or local files

• 🔄 Resize, rotate, flip, blur, sharpen, and more

• 📦 Batch process multiple images

• 🎨 Convert between JPEG, PNG, WebP, AVIF, TIFF

• ✂️ Auto-crop borders and whitespace

• 🎯 Smart crop with attention detection

• 🌫️ Generate low-quality placeholders (LQIP)

• 💧 Add watermarks (image or text) with full control

• 🌟 Generate favicons in all required sizes and formats

Related MCP server: Image Toolkit MCP Server

Installation

Run this command to add the MCP server:

claude mcp add image-optimizer -- npx -y mcp-image-optimizer

See Claude Code MCP docs for more info.

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "image-optimizer": {
      "command": "npx",
      "args": ["mcp-image-optimizer"]
    }
  }
}

Add the following configuration to your OpenAI Codex MCP server settings:

[mcp_servers.image-optimizer]
args = ["-y", "mcp-image-optimizer"]
command = "npx"

See OpenAI Codex for more information.

Add to your VS Code settings for MCP extensions like Cline or Continue:

{
  "image-optimizer": {
    "command": "npx",
    "args": ["mcp-image-optimizer"]
  }
}

Navigate to Settings → Cursor Settings → MCP → Add new global MCP server

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "image-optimizer": {
      "command": "npx",
      "args": ["mcp-image-optimizer"]
    }
  }
}

Install globally for faster startup:

npm install -g mcp-image-optimizer

Then use this simpler config in any client:

{
  "command": "mcp-image-optimizer"
}

Usage Examples

Ask your AI assistant:

• "Optimize ~/Desktop/photo.jpg to 800px width"

• "Convert https://images.pexels.com/photos/32206277/pexels-photo-32206277.jpeg to WebP"

• "Batch optimize all images in ~/Downloads/"

• "Create a 200x200 thumbnail with smart crop"

• "Generate a placeholder for lazy loading"

• "Add my company logo as watermark to product images"

• "Add 'Copyright 2025' text watermark"

• "Generate all favicon sizes from my logo"

Available Tools

Resize, convert, and transform images.

Example:

"Optimize image.jpg to 800px width with 85% quality"

Parameters:

• input - Image path or URL

• output - Output file path

• width - Target width in pixels

• height - Target height in pixels

• quality - Quality 1-100 for lossy formats

• format - Output format (jpeg, png, webp, avif, tiff)

• fit - Resize fit mode (cover, contain, fill, inside, outside)

• Plus rotate, flip, grayscale, blur, sharpen, normalize

Process multiple images at once.

Example:

"Optimize all images in ~/Pictures/ to 1200px width"

Parameters:

• inputs - Array of image paths or URLs

• outputDir - Output directory

• width, height, quality, format - Same as single image

• prefix - Add to filename start

• suffix - Add to filename end

Extract image metadata.

Example:

"Get info about image.jpg"

Returns:

• Dimensions, format, color space

• File size, DPI

• EXIF data presence

Remove borders and whitespace automatically.

Example:

"Auto-crop screenshot.png to remove white borders"

Parameters:

• input - Image path or URL

• output - Output file path

• threshold - Color similarity threshold 0-100

• backgroundColor - Background to detect

Intelligent cropping to specific dimensions.

Example:

"Smart crop portrait.jpg to 500x500 square"

Parameters:

• input - Image path or URL

• output - Output file path

• width, height - Target dimensions

• strategy - "attention" or "entropy"

Generate low-quality image placeholders for lazy loading.

Example:

"Create a blurred placeholder for hero-image.jpg"

Parameters:

• input - Image path or URL

• width - Placeholder width (default: 20)

• height - Placeholder height (auto if not set)

• quality - JPEG quality 1-100 (default: 40)

• blur - Blur amount 0.3-1000 (default: 5)

• format - "base64", "datauri", or "file"

Add image or text watermarks with positioning and styling.

Example:

"Add logo.png as watermark to photo.jpg in bottom-right corner"
"Add 'Copyright 2025' text watermark with 50% opacity"
"Add 'CONFIDENTIAL' diagonally across the document"

Parameters:

• input - Image path or URL

• output - Output file path

• watermark - Path/URL to watermark image, base64 data, or text

• position - Corner, center, diagonal, or tile pattern

• opacity - Transparency 0-1

• scale - Size relative to base image

• margin - Distance from edges

• blend - Blend mode for effects

• Text options: text, fontSize, fontColor, fontFamily

Generate all favicon sizes and formats for modern web apps.

Example:

"Generate favicons from logo.png and save to ./public"
"Create all icon sizes for my PWA"

Parameters:

• input - Source image (recommend 512x512 or larger)

• outputDir - Directory to save all favicon files

• sizes - Custom sizes array (default: all standard sizes)

• platforms - Target platforms: web, apple, android, microsoft, all

• generateManifest - Create manifest.json snippet for PWAs

Generated files:

• PNG favicons in all sizes (16x16 to 512x512)

• apple-touch-icon.png (180x180)

• android-chrome-192x192.png, android-chrome-512x512.png

• mstile-150x150.png (Microsoft tile)

• favicon-html.txt (ready-to-use HTML tags)

• manifest-icons.json (PWA configuration)

Path Support

• ✅ URLs: https://example.com/image.jpg

• ✅ Absolute paths: /Users/name/Desktop/image.jpg

• ✅ Home directory: ~/Desktop/image.jpg

• ⚠️ Relative paths: Works with cwd config setting

To use relative paths, add a working directory:

{
  "command": "npx",
  "args": ["mcp-image-optimizer"],
  "cwd": "/Users/yourname/Desktop"
}

Requirements

• Node.js 22+ (npx handles this automatically)

• Compatible MCP client

Troubleshooting

"Command not found"

• Make sure Node.js is installed: node --version

• Try the global install method

"File not found"

• Use absolute paths: /Users/name/Desktop/image.jpg

• Check file permissions

"MCP tools not available"

• Restart your MCP client after configuration

• Check config file is valid JSON

License

MIT

Links

• GitHub Repository

• NPM Package

• Report Issues