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

Installation

<details open> <summary>Install in Claude Code</summary>

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.

</details>

<details> <summary>Install in Claude Desktop</summary>

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"]
    }
  }
}

</details>

<details> <summary>Install in OpenAI Codex</summary>

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.

</details>

<details> <summary>Install in VSCode</summary>

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

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

</details>

<details> <summary>Install in Cursor</summary>

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"]
    }
  }
}

</details>

<details> <summary>Alternative: Global Install</summary>

Install globally for faster startup:

npm install -g mcp-image-optimizer

Then use this simpler config in any client: ``json { "command": "mcp-image-optimizer" } ``

</details>

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

<details> <summary><code>optimize_image</code></summary>

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

</details>

<details> <summary><code>batch_optimize</code></summary>

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

</details>

<details> <summary><code>get_image_info</code></summary>

Extract image metadata.

Example: `` "Get info about image.jpg" ``

Returns:

Dimensions, format, color space
File size, DPI
EXIF data presence

</details>

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

</details>

<details> <summary><code>smart_crop</code></summary>

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"

</details>

<details> <summary><code>create_placeholder</code></summary>

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"

</details>

<details> <summary><code>add_watermark</code></summary>

Add image or text watermarks with positioning and styling.

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

</details>

<details> <summary><code>generate_favicon</code></summary>

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)

</details>

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: ``json { "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

mcp-image-optimizer