WebP Batch Converter
Batch convert PNG, JPG, and JPEG images to WebP format with options for quality, lossless mode, and multi-threaded processing.
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_webp
tool will be available in your AI conversations
🔧 Technical Details
Conversion Strategy
-
Primary Engine: Google's
cwebp
tool (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
.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
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.
Related Servers
FTP Access
Provides access to an FTP server for file operations.
Excel Analyser MCP
Read and analyze Excel (.xlsx) and CSV (.csv) files with scalable, chunked, and column-specific data access, ideal for large datasets.
Lumina Docs
An intelligent structured document management system designed for large language models.
File Converter
Convert various file formats for documents and images, such as DOCX, PDF, CSV, and more.
Claude Text Editor
An MCP server for viewing, editing, and creating text files, based on the Claude built-in text editor tool.
File Convert MCP Server
Convert files between various formats, including images, documents, audio, video, and more.
YggTorrent
A server to programmatically interact with the YggTorrent file-sharing platform.
Cross-Platform Filesystem MCP Server
A cross-platform filesystem server for Linux, macOS, and Windows with secure path restrictions.
Filesystem MCP Server
Perform filesystem operations within specified directories.
MCP Excel Reader
Read large Excel files with automatic chunking and pagination support.