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
npm install -g webp-batch-mcp
Local Development
git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build
Docker
docker build -t webp-batch .
docker run -v /path/to/images:/data webp-batch
🚀 Usage
Command Line Interface
node dist/cli.js [options]
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
# Convert all images in current directory
node dist/cli.js
# High quality conversion of specific directory
node dist/cli.js --src ./photos --quality 95 --preserve-meta
# Lossless conversion with overwrite
node dist/cli.js --src ./images --lossless --overwrite
# Batch process to output directory
node dist/cli.js --src ./input --flat ./output --threads 8
MCP Server
The MCP server exposes a single tool: convert_to_webp
Tool Parameters
{
"src": "string", // Source directory (default: ".")
"quality": "number", // Quality 0-100 (default: 75)
"lossless": "boolean", // Lossless mode (default: false)
"overwrite": "boolean", // Replace originals (default: false)
"threads": "number", // Concurrent threads (default: CPU count)
"preserveMeta": "boolean", // Keep metadata (default: false)
"flat": "string" // Output directory (optional)
}
⚙️ How to Add This Server in Cursor
- Clone and build the project:
git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build
- Open Cursor Settings
- Navigate to Features → MCP
- Add a new server configuration:
{
"mcpServers": {
"webp-batch": {
"command": "node",
"args": ["/path/to/webp-batch-mcp/dist/server.js"]
}
}
}
- Restart Cursor
- The
convert_to_webptool will be available in your AI conversations
🔧 Technical Details
Conversion Strategy
-
Primary Engine: Google's
cwebptool (included in libwebp-tools)- Fastest performance
- Best compression
- Full feature support
-
Fallback Engine: Sharp (Node.js)
- Pure JavaScript implementation
- No external dependencies
- Cross-platform compatibility
Output Behavior
- Default: Creates
.webpfiles 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
npm run build
Testing
npm test
Development Mode
npm run dev
📊 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 frameworksharp- Image processing fallbackchalk- Colorized terminal outputcommander- CLI argument parsingglob- File pattern matchingp-limit- Concurrency control
Development
typescript- Type safetytsup- Fast TypeScript bundlerjest- Testing framework
📄 License
MIT License - see LICENSE file for details.
🤝 Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
🆘 Support
For issues and feature requests, please use the GitHub issue tracker.