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

Download Node.js

安装配置

1. 获取 TinyPNG API 密钥

1. 访问 TinyPNG Developer API
2. 使用邮箱注册账号
3. 获取免费的 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 次调用
  • 组合操作会累计调用次数

相关链接

• Model Context Protocol SDK
• TinyPNG API 文档