🖼️ MCP Image Compression and OSS Upload Tool

This is a professional image processing MCP (Model Context Protocol) tool, designed specifically for the Cursor editor. It supports high-quality lossless compression of various formats and features Alibaba Cloud OSS upload capabilities.

🎯 Features

🖼️ Supported Formats

• JPEG/JPG - Optimized using MozJPEG algorithm
• PNG - Palette optimization and highest compression level
• WebP - Near-lossless and lossless compression
• AVIF - Next-generation image format
• TIFF - Professional image format support

⚡ Core Functions

1. Single Image Compression (compress_image)

   • Intelligent format detection and optimization
   • Customizable compression quality (1-100)
   • Format conversion support
   • Option to keep or remove metadata

2. Batch Compression (compress_folder)

   • Recursively processes folders and subfolders
   • Batch format conversion
   • Compression progress statistics

3. Image Information (get_image_info)

   • Detailed image metadata
   • File size and dimensions
   • Color space and channel information

4. OSS Upload (upload_to_oss)

   • Single image upload to Alibaba Cloud OSS
   • Automatically generates unique filenames
   • Returns full access URL

5. Batch OSS Upload (upload_folder_to_oss)

   • Batch uploads images from a folder
   • Recursively processes subfolders
   • Detailed upload statistics

🚀 Installation

Method 1: Using npm Package (Recommended)

1. Directly with npx (No Installation Required)

In the Cursor's MCP configuration:
json
{
"mcpServers": {
"mcp-img-compress-oss": {
"command": "npx",
"args": ["-y", "mcp-img-compress-oss@latest"],
"env": {
"OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com",
"OSS_ACCESS_KEY_ID": "your_access_key_id",
"OSS_ACCESS_KEY_SECRET": "your_access_key_secret",
"OSS_BUCKET": "your_bucket_name",
"OSS_REGION": "oss-cn-hangzhou",
"OSS_PATH": "images"
}
}
}
}

2. Global Installation

bash
npm install -g mcp-img-compress-oss

Then in the Cursor configuration:
json
{
"mcpServers": {
"mcp-img-compress-oss": {
"command": "mcp-img-compress-oss",
"env": {
"OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com",
"OSS_ACCESS_KEY_ID": "your_access_key_id",
"OSS_ACCESS_KEY_SECRET": "your_access_key_secret",
"OSS_BUCKET": "your_bucket_name",
"OSS_REGION": "oss-cn-hangzhou",
"OSS_PATH": "images"
}
}
}
}

Method 2: Local Development Installation

1. Clone the Project

bash
git clone https://github.com/HongHaiyang/mcp-img-compress-oss.git
cd mcp-img-compress-oss

2. Install Dependencies

bash
npm install

3. Automated Setup

bash
./setup.sh

Or start manually:
bash
npm start

4. Configure in Cursor

The configuration file is automatically created at: ~/.cursor/mcp_servers.json

For manual configuration:
json
{
"mcpServers": {
"mcp-img-compress-oss": {
"command": "node",
"args": ["/path/to/mcp-img-compress-oss/src/index.js"],
"cwd": "/path/to/mcp-img-compress-oss",
"env": {}
}
}
}

💡 Quick Usage

After configuration, interact with Claude in Cursor:

Basic Compression

Please compress this image: /path/to/image.jpg, set quality to 90

Batch Processing

Please batch compress all images in the /path/to/images/ folder, convert to WebP format

Upload to OSS

Please upload this image to OSS: /path/to/image.jpg

Advanced Usage

Please compress /path/to/input.jpg, output as /path/to/output.webp, set quality to 95, keep metadata, then upload to OSS

📊 Compression Effects

Typical Compression Ratios

• JPEG: 10-30% size reduction
• PNG: 20-50% size reduction
• WebP: 25-35% smaller than JPEG
• AVIF: 50% smaller than JPEG

Quality Setting Recommendations

• 95-100: Lossless or near-lossless, suitable for professional use
• 85-95: High quality, suitable for websites and printing
• 70-85: Medium quality, suitable for web display
• 50-70: Compression priority, suitable for thumbnails

🛠️ Project Structure

mcp-img-compress-oss/
├── package.json # Project configuration and dependencies
├── src/
│ ├── index.js # Main MCP server file
│ ├── compressImage.js # Image compression module
│ ├── compressFolder.js # Batch compression module
│ ├── getImageInfo.js # Image information module
│ ├── uploadToOSS.js # OSS upload module
│ └── uploadFolderToOSS.js # Batch OSS upload module
├── README.md # Main documentation
├── OSS_SETUP.md # Complete OSS setup guide
├── USAGE_GUIDE.md # Usage guide and troubleshooting
├── DEFAULT_PARAMS.md # Technical parameter explanation
├── CHANGELOG.md # Changelog
└── setup.sh # Automation script## 📚 Detailed Documentation

• OSS Configuration Guide - Comprehensive guide for configuring Alibaba Cloud OSS
• Usage Guide - Detailed usage examples and troubleshooting
• Technical Parameters - Default parameters and lossless compression explanation
• Changelog - Version update records

🔍 Development and Debugging

Development Mode

bash
npm run dev # Automatically restarts on file changes

Test Server

bash
node src/index.js

Environment Variables Verification

bash
node debug_env.js

💪 Tech Stack

• Node.js 18+ - Runtime environment
• Sharp - High-performance image processing
• MozJPEG - JPEG optimization encoder
• Ali-OSS - Alibaba Cloud Object Storage
• MCP Protocol - Model Context Protocol

🤝 Contributions

Feel free to submit Issues and Pull Requests to help improve this project!

📄 License

MIT License

Getting Started: After setting up according to the installation steps above, you can enjoy efficient image compression and OSS upload features in Cursor!

For any issues, please refer to the Usage Guide and OSS Configuration Guide.