Image Convert

💡 If this tool saves you time, please consider buying me a coffee! Your support helps maintain and improve this project.

---

A Model Context Protocol (MCP) server for high-performance image format conversion supporting WebP and AVIF formats with parallel processing capabilities.

🚀 Features

• Multiple Format Support: Convert images to WebP, AVIF, or both formats simultaneously
• Batch Processing: Process entire directories with configurable parallel workers
• Image Resizing: Optional width/height constraints with aspect ratio preservation
• Quality Control: Configurable quality settings for both WebP and AVIF
• High Performance: Multi-process parallel execution for batch operations
• Flexible Input: Supports PNG, JPG, JPEG, TIFF, BMP, and WebP as input formats

📋 Requirements

• Python 3.11+
• MCP Python SDK (mcp>=1.0.0)
• Pillow (PIL)
• pillow-avif-plugin
• libavif-dev (system dependency)

🔧 Installation

Using pip

cd /path/to/image-convert-mcp
pip install -e .

Or install requirements directly:

pip install -r requirements.txt

💻 CLI Usage

After installation, you can use the image-convert command directly:

# Convert to both WebP and AVIF
image-convert photo.png

# Convert to WebP only
image-convert photo.png -f webp -q 85

# Use a preset
image-convert photo.png --preset thumbnail

# Batch convert a directory
image-convert ./images/ --batch -f webp

# Show compression statistics
image-convert photo.png -f webp --stats

# List available presets
image-convert --list-presets

Available Presets

Preset	Description
web	Optimized for web (WebP, quality 80, max 1920px)
thumbnail	Small thumbnails (WebP, 300x300)
social	Social media images (1200x630)
hd	HD resolution (1920x1080)
4k	4K resolution (3840x2160)
archive	High quality archival (both formats)
lossless	Lossless WebP compression
max-compression	Maximum file size reduction (AVIF)

Using Docker

docker build -t image-convert-mcp .

📖 Usage

The MCP server implements the Model Context Protocol with support for both Stdio and Unified HTTP transports.

🚌 Transport Modes

The server supports two transport mechanisms:

1. Stdio (Default)

Standard communication via stdin/stdout. Ideal for local use with MCP clients like Claude Desktop.

python mcp_server.py --transport stdio

2. HTTP (Unified)

Web-based communication via HTTP. This is the modern, recommended transport for remote MCP access.

python mcp_server.py --transport http --host 0.0.0.0 --port 8000

When running in HTTP mode, the server provides a unified MCP endpoint at the root path (e.g., http://localhost:8000/).

MCP Tools

convert_image_single

Convert a single image to WebP and/or AVIF format.

Parameters:

• input_path (required): Path to the input image file
• output_dir (optional): Directory for output files (default: same as input)
• format (optional): Output format - "webp", "avif", or "both" (default: "both")
• webp_quality (optional): WebP quality 1-100 (default: 80)
• avif_quality (optional): AVIF quality 1-100 (default: 50)
• lossless (optional): Enable lossless WebP compression (default: false)
• max_width (optional): Maximum output width
• max_height (optional): Maximum output height

convert_image_batch

Convert multiple images in a directory to WebP and/or AVIF format.

Parameters:

• input_path (required): Path to directory containing images
• output_dir (optional): Directory for output files (default: same as input)
• format (optional): Output format - "webp", "avif", or "both" (default: "both")
• webp_quality (optional): WebP quality 1-100 (default: 80)
• avif_quality (optional): AVIF quality 1-100 (default: 50)
• lossless (optional): Enable lossless WebP compression (default: false)
• max_width (optional): Maximum output width
• max_height (optional): Maximum output height
• workers (optional): Number of parallel workers (default: CPU count)

🔑 Parameters

Parameter	Type	Default	Description
mode	string	"single"	Processing mode: "single" or "batch"
input_path	string	required	Path to image file (single mode) or directory (batch mode)
output_dir	string	parent of input	Directory for output files
format	string	"both"	Output format: "webp", "avif", or "both"
webp_quality	int	80	WebP quality (1-100)
avif_quality	int	50	AVIF quality (1-100)
lossless	bool	false	Enable lossless compression for WebP
max_width	int	null	Maximum output width (maintains aspect ratio)
max_height	int	null	Maximum output height (maintains aspect ratio)
workers	int	CPU count	Number of parallel workers (batch mode only)

🐳 Docker Usage

# Build the image
docker build -t image-convert-mcp .

# Run conversion
echo '{"params":{"input_path":"/app/input.png","format":"webp"}}' | \
  docker run -i -v /path/to/images:/app image-convert-mcp

🔌 MCP Configuration

Add to your MCP settings file (e.g., opencode.json):

{
  "mcpServers": {
    "image-convert": {
      "command": "python",
      "args": ["/path/to/image-convert-mcp/mcp_server.py"],
      "disabled": false
    }
  }
}

Or using Docker:

{
  "mcpServers": {
    "image-convert": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${workspaceFolder}:/workspace",
        "image-convert-mcp"
      ],
      "disabled": false
    }
  }
}

📊 Output Format

Single Mode

{
  "result": {
    "input": "/path/to/input.png",
    "webp": "/path/to/output/input.webp",
    "avif": "/path/to/output/input.avif"
  }
}

Batch Mode

{
  "result": [
    {
      "input": "/path/to/image1.png",
      "webp": "/path/to/output/image1.webp"
    },
    {
      "input": "/path/to/image2.jpg",
      "webp": "/path/to/output/image2.webp"
    }
  ]
}

🎯 Supported Input Formats

• PNG (.png)
• JPEG (.jpg, .jpeg)
• TIFF (.tiff)
• BMP (.bmp)
• WebP (.webp)

🛠️ Development

Project Structure

image-convert-mcp/
├── mcp_server.py      # Main MCP server implementation
├── requirements.txt   # Python dependencies
└── Dockerfile         # Docker container definition

🤖 For AI Agents

Quick Summary: This MCP server converts images to WebP/AVIF formats for web optimization.

Task	Tool	Example
Single image	convert_image_single	{"input_path": "/path/to/image.png", "format": "webp"}
Batch directory	convert_image_batch	{"input_path": "/path/to/dir/", "workers": 4}

📖 See AGENT_GUIDE.md for detailed usage patterns.

☕ Support This Project

If this MCP server saves you time or helps your projects, consider supporting its development:

Your support enables:

• 🚀 New format support (JPEG XL, HEIC)
• 📊 Progress reporting features
• 🔒 Security enhancements
• 📚 Better documentation

📝 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

🔮 Roadmap

• Support for JPEG XL format
• Metadata preservation options
• Progress reporting for long operations
• Comprehensive test suite
• Input validation and security enhancements
• Caching for frequently converted images