Content
# 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:
```bash
claude mcp add image-optimizer -- npx -y mcp-image-optimizer
```
See [Claude Code MCP docs](https://github.com/anthropics/claude-code) 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`
```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:
```toml
[mcp_servers.image-optimizer]
args = ["-y", "mcp-image-optimizer"]
command = "npx"
```
See [OpenAI Codex](https://openai.com/codex) for more information.
</details>
<details>
<summary>Install in VSCode</summary>
Add to your VS Code settings for MCP extensions like Cline or Continue:
```json
{
"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`:
```json
{
"mcpServers": {
"image-optimizer": {
"command": "npx",
"args": ["mcp-image-optimizer"]
}
}
}
```
</details>
<details>
<summary>Alternative: Global Install</summary>
Install globally for faster startup:
```bash
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>
<details>
<summary><code>auto_crop</code></summary>
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.
**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`
</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
## Links
- [GitHub Repository](https://github.com/piephai/mcp-image-optimizer)
- [NPM Package](https://www.npmjs.com/package/mcp-image-optimizer)
- [Report Issues](https://github.com/piephai/mcp-image-optimizer/issues)
