README.md•5.11 kB
# 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.
<a href="https://glama.ai/mcp/servers/@mhe8mah/webp-batch-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mhe8mah/webp-batch-mcp/badge" alt="WebP Batch Converter MCP server" />
</a>
## 🌟 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
```bash
npm install -g webp-batch-mcp
```
### Local Development
```bash
git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build
```
### Docker
```bash
docker build -t webp-batch .
docker run -v /path/to/images:/data webp-batch
```
## 🚀 Usage
### Command Line Interface
```bash
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
```bash
# 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
```json
{
"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
1. Clone and build the project:
```bash
git clone https://github.com/mhe8mah/webp-batch-mcp.git
cd webp-batch-mcp
npm install
npm run build
```
2. Open Cursor Settings
3. Navigate to **Features** → **MCP**
4. Add a new server configuration:
```json
{
"mcpServers": {
"webp-batch": {
"command": "node",
"args": ["/path/to/webp-batch-mcp/dist/server.js"]
}
}
}
```
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
```bash
npm run build
```
### Testing
```bash
npm test
```
### Development Mode
```bash
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 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](https://github.com/mhe8mah/webp-batch-mcp/issues).