Image Convert MCP Server

💡 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

Related MCP server: WebP Batch Converter

📋 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

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

🐳 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.

📖 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