README.md•6.22 kB
# TinyPNG MCP Server 使用指南
本项目是一个基于 [Model Context Protocol (MCP)](https://www.npmjs.com/package/@modelcontextprotocol/sdk) 的图片压缩服务器，使用 [TinyPNG API](https://tinypng.com/developers/reference/nodejs) 来优化图片。
## 功能特性
- ✅ 支持批量压缩目录中的所有图片
- ✅ 支持图片格式转换（PNG、JPEG、WebP、AVIF 互转）
- ✅ 支持图片尺寸调整和智能裁剪
- ✅ 支持多种图片格式：`.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`
- ✅ 自动覆盖原始文件（节省存储空间）
- ✅ 详细的压缩报告（文件大小变化、压缩比例）
- ✅ 安全的 API 密钥管理（通过环境变量）
- ✅ 完整的错误处理和日志记录
## 前置环境
需要安装Node.js环境
> Recommend Node.js version >= 20
> [Download Node.js](https://nodejs.org/en/download)
## 安装配置
### 1. 获取 TinyPNG API 密钥
1. 访问 [TinyPNG Developer API](https://tinypng.com/developers)
2. 使用邮箱注册账号
3. 获取免费的 API 密钥（每月 500 次免费压缩）
### 2. 配置 MCP 客户端
创建或修改你的 MCP 配置文件，目前支持的客户端（或命令行工具）有Cursor，gemini-cli，Claude Code，Claude Desktop，Trae...
```json
{
"mcpServers": {
"mcp-tinify-image": {
"command": "npx",
"args": [
"-y",
"mcp-tinify-image"
],
"env": {
"TINIFY_API_KEY": "YOUR_TINIFY_API_KEY"
}
}
}
}
```
## 使用方法
### 可用工具
本 MCP 服务器提供三个核心工具，满足不同的图片处理需求：
| 工具名称 | 主要功能 | 适用场景 |
|---------|----------|----------|
| `minify_image` | 批量压缩图片 | 减少文件大小，优化存储 |
| `resize_image` | 调整图片尺寸 | 生成缩略图，适配不同设备 |
| `convert_image` | 转换图片格式 | Web 优化，兼容性处理 |
#### `minify_image`
压缩指定目录中的所有支持的图片文件。支持嵌套结构。
**参数：**
- `directoryPath` (string): 包含要压缩图片的目录路径
**示例：**
```bash
# 压缩 ./images 目录中的所有图片
minify_image {
"directoryPath": "./images"
}
```
**输出示例：**
```
✅ photo1.jpg: 2048000 → 512000 bytes (75.0% reduction)
✅ screenshot.png: 1024000 → 256000 bytes (75.0% reduction)
❌ corrupted.jpg: Invalid image format
📊 Total compressions used this month: 15
✅ Successfully compressed: 2 images
❌ Failed to compress: 1 images
```
#### `resize_image`
调整指定图片尺寸。
**参数：**
```
{
imagePath: z.string().describe('Path to the image file to resize'),
width: z.number().optional().describe('Target width in pixels'),
height: z.number().optional().describe('Target height in pixels'),
method: z.enum(['fit', 'scale', 'cover', 'thumb']).describe('Resize method'),
outputPath: z.string().optional().describe('Output path for resized image'),
},
```
### method参数模式说明
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `fit` | 保持宽高比，适配指定尺寸 | 缩略图生成 |
| `scale` | 按比例缩放 | 等比缩放 |
| `cover` | 裁剪填充指定尺寸 | 封面图制作 |
| `thumb` | 智能缩略图模式 | 头像处理 |
**示例：**
```bash
# 调整图片尺寸
@icon-logo.png 帮我修改图片尺寸，高度60宽度60
```
**测试结果：**
```
✅ 调整结果
原图片: icon-logo.png (4.4KB)
新图片: icon-logo-60x60.png (1.9KB)
尺寸: 调整为 60x60 像素
调整方法: fit (保持宽高比)
文件大小减少: 57.3%
```
#### `convert_image`
转换图片格式，支持 PNG、JPEG、WebP、AVIF 格式之间的相互转换。
**参数：**
```javascript
{
imagePath: string, // 源图片文件路径
targetFormats: string | string[], // 目标格式，支持单个或多个格式
backgroundColor?: string, // 可选：透明背景填充色
outputPath?: string // 可选：自定义输出路径
}
```
**支持的格式：**
- `image/png` - PNG 格式
- `image/jpeg` - JPEG 格式
- `image/webp` - WebP 格式
- `image/avif` - AVIF 格式
**示例：**
```bash
# PNG 转 WebP
convert_image {
"imagePath": "./photo.png",
"targetFormats": "image/webp"
}
# 多格式转换（选择最小的）
convert_image {
"imagePath": "./large-image.png",
"targetFormats": ["image/webp", "image/avif"]
}
# 透明 PNG 转 JPEG（添加白色背景）
convert_image {
"imagePath": "./logo.png",
"targetFormats": "image/jpeg",
"backgroundColor": "white"
}
# 自定义输出路径
convert_image {
"imagePath": "./input.png",
"targetFormats": "image/webp",
"outputPath": "./optimized/output.webp"
}
```
**输出示例：**
```
✅ Image converted successfully: logo.png
🔄 image/png → image/webp
📊 Size: 512000 → 128000 bytes (+75.0%)
🎯 Target format(s): image/webp
💾 Saved to: ./logo.webp
📊 Total API calls used: 3
```
**应用场景：**
- **Web 优化**: 将 PNG 转换为体积更小的 WebP/AVIF 格式
- **兼容性处理**: 为旧浏览器提供 JPEG/PNG 备选格式
- **透明处理**: 将透明 PNG 转换为 JPEG 并添加背景色
- **现代格式支持**: 利用 AVIF/WebP 的高压缩比优势
## 支持的图片格式
根据 [TinyPNG 官方文档](https://tinypng.com/developers/reference/nodejs)，支持以下格式：
- **PNG** - 便携式网络图形
- **JPEG/JPG** - 联合图像专家组格式
- **WebP** - 现代网络图片格式
- **AVIF** - AV1 图像文件格式
## 限制说明
- **免费账户**: 每月 500 次 API 调用（包括压缩、调整尺寸、格式转换）
- **付费账户**: 根据订阅计划不同
- **文件大小**: 单个文件最大 5MB
- **并发请求**: TinyPNG 有合理的速率限制
- **API 计费规则**:
- 图片压缩（`minify_image`）: 每张图片 1 次调用
- 尺寸调整（`resize_image`）: 每张图片 1 次调用
- 格式转换（`convert_image`）: 每张图片 1 次调用
- 组合操作会累计调用次数
## 相关链接
- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [TinyPNG API 文档](https://tinypng.com/developers/reference/nodejs)