MCP 服务器

image-convert-mcp

MCP server for converting images to WebP and AVIF formats with batch processing and parallel execution.

README

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

📋 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