README.md•3.77 kB
# TinyPNG MCP Server 使用指南
本项目是一个基于 [Model Context Protocol (MCP)](https://www.npmjs.com/package/@modelcontextprotocol/sdk) 的图片压缩服务器，使用 [TinyPNG API](https://tinypng.com/developers/reference/nodejs) 来优化图片。
## 功能特性
- ✅ 支持批量压缩目录中的所有图片
- ✅ 支持多种图片格式：`.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"
}
}
}
}
```
## 使用方法
### 可用工具
#### `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%
```
## 支持的图片格式
根据 [TinyPNG 官方文档](https://tinypng.com/developers/reference/nodejs)，支持以下格式：
- **PNG** - 便携式网络图形
- **JPEG/JPG** - 联合图像专家组格式
- **WebP** - 现代网络图片格式
- **AVIF** - AV1 图像文件格式
## 限制说明
- **免费账户**: 每月 500 次压缩
- **付费账户**: 根据订阅计划不同
- **文件大小**: 单个文件最大 5MB
- **并发请求**: TinyPNG 有合理的速率限制
## 相关链接
- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [TinyPNG API 文档](https://tinypng.com/developers/reference/nodejs)