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 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

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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

An MCP server that enables batch conversion of images to WebP format with configurable options like quality settings, lossless mode, and multi-threading support.

Related MCP Servers

WebPerfect MCP Server
splendasucks
A
security
A
license
A
quality
An intelligent MCP server with a fully automated batch pipeline for web-ready images. Features include noise reduction, auto levels/curves, JPEG artifact removal, 4K resizing, smart sharpening with shadow/highlight enhancement, and advanced WebP conversion.
Last updated -
1
5
JavaScript
MIT License
MCP NPX Fetch
tokenizin-agency
A
security
A
license
A
quality
A powerful MCP server for fetching and transforming web content into various formats (HTML, JSON, Markdown, Plain Text) with ease.
Last updated -
4
146
12
TypeScript
MIT License
MCP Server Fetch Python
tatn
A
security
A
license
A
quality
An MCP server for fetching and transforming web content into various formats.
Last updated -
4
4
Python
MIT License
webdev-mcp
zueai
-
security
-
license
-
quality
An MCP server that provides web development tools including taking screenshots of screens, enabling AI agents to capture and analyze visual content during development.
Last updated -
2
TypeScript

View all related MCP servers

WebP Batch Converter