TinyPNG MCP Server 使用指南
本项目是一个基于 Model Context Protocol (MCP) 的图片压缩服务器，使用 TinyPNG API 来优化图片。
功能特性
- ✅ 支持批量压缩目录中的所有图片
- ✅ 支持图片格式转换（PNG、JPEG、WebP、AVIF 互转）
- ✅ 支持图片尺寸调整和智能裁剪
- ✅ 支持多种图片格式：
.png,.jpg,.jpeg,.webp,.avif - ✅ 自动覆盖原始文件（节省存储空间）
- ✅ 详细的压缩报告（文件大小变化、压缩比例）
- ✅ 安全的 API 密钥管理（通过环境变量）
- ✅ 完整的错误处理和日志记录
前置环境
需要安装Node.js环境
Recommend Node.js version >= 20
安装配置
1. 获取 TinyPNG API 密钥
- 访问 TinyPNG Developer API
- 使用邮箱注册账号
- 获取免费的 API 密钥（每月 500 次免费压缩）
2. 配置 MCP 客户端
创建或修改你的 MCP 配置文件，目前支持的客户端（或命令行工具）有Cursor，gemini-cli，Claude Code，Claude Desktop，Trae...
{
"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): 包含要压缩图片的目录路径
示例：
# 压缩 ./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 | 智能缩略图模式 | 头像处理 |
示例：
# 调整图片尺寸
@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 格式之间的相互转换。
参数：
{
imagePath: string, // 源图片文件路径
targetFormats: string | string[], // 目标格式，支持单个或多个格式
backgroundColor?: string, // 可选：透明背景填充色
outputPath?: string // 可选：自定义输出路径
}
支持的格式：
image/png- PNG 格式image/jpeg- JPEG 格式image/webp- WebP 格式image/avif- AVIF 格式
示例：
# 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 官方文档，支持以下格式：
- PNG - 便携式网络图形
- JPEG/JPG - 联合图像专家组格式
- WebP - 现代网络图片格式
- AVIF - AV1 图像文件格式
限制说明
- 免费账户: 每月 500 次 API 调用（包括压缩、调整尺寸、格式转换）
- 付费账户: 根据订阅计划不同
- 文件大小: 单个文件最大 5MB
- 并发请求: TinyPNG 有合理的速率限制
- API 计费规则:
- 图片压缩（
minify_image）: 每张图片 1 次调用 - 尺寸调整（
resize_image）: 每张图片 1 次调用 - 格式转换（
convert_image）: 每张图片 1 次调用 - 组合操作会累计调用次数
- 图片压缩（