WebP Batch Converter

A Model Context Protocol (MCP) server for batch converting images to WebP format with cross-platform support. Works seamlessly with MCP-aware IDEs like Cursor.

🌟 Features

• 🖼️ Batch conversion of PNG, JPG, and JPEG files to WebP

• 🌍 Cross-platform support (macOS, Linux, Windows)

• ⚡ Multi-threaded processing for fast conversions

• 🎛️ Flexible options including quality control, lossless mode, and metadata preservation

• 📊 Detailed reporting with file sizes and savings statistics

• 🔧 Dual engine support - prefers Google's cwebp, falls back to Sharp

• 🎯 MCP integration for use in AI-powered development environments

📦 Installation

Global Installation

Local Development

Docker

🚀 Usage

Command Line Interface

Options

• --src <dir> - Source directory to scan (default: current directory)

• --quality <0-100> - WebP quality setting (default: 75)

• --lossless - Use lossless encoding (recommended for PNG)

• --overwrite - Replace original files with WebP versions

• --threads <n> - Number of concurrent conversions (default: CPU count)

• --preserve-meta - Preserve EXIF and ICC metadata

• --flat <dir> - Output all WebP files to specified directory

Examples

MCP Server

The MCP server exposes a single tool: convert_to_webp

Tool Parameters

⚙️ How to Add This Server in Cursor

1. Clone and build the project:

2. Open Cursor Settings

3. Navigate to Features → MCP

4. Add a new server configuration:

5. Restart Cursor

6. The convert_to_webp tool will be available in your AI conversations

🔧 Technical Details

Conversion Strategy

1. Primary Engine: Google's cwebp tool (included in libwebp-tools)

   • Fastest performance

   • Best compression

   • Full feature support

2. Fallback Engine: Sharp (Node.js)

   • Pure JavaScript implementation

   • No external dependencies

   • Cross-platform compatibility

Output Behavior

• Default: Creates .webp files alongside originals

• Overwrite mode: Replaces originals with WebP versions

• Flat mode: Outputs all WebP files to specified directory

• Metadata preservation: Maintains EXIF and ICC profiles when requested

Performance

• Utilizes all CPU cores by default

• Processes images concurrently using p-limit

• Provides real-time progress feedback

• Reports detailed conversion statistics

🛠️ Development

Building

Testing

Development Mode

📊 Test Results

Verified with real web images:

• JPEG (35KB → 17KB): 51% space savings

• PNG (7.9KB → 2.8KB): 65% space savings

• Overall: 53% average compression

📋 Dependencies

Runtime

• @modelcontextprotocol/sdk - MCP server framework

• sharp - Image processing fallback

• chalk - Colorized terminal output

• commander - CLI argument parsing

• glob - File pattern matching

• p-limit - Concurrency control

Development

• typescript - Type safety

• tsup - Fast TypeScript bundler

• jest - Testing framework

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass

5. Submit a pull request

🆘 Support

For issues and feature requests, please use the GitHub issue tracker.