TinyPNG MCP Server 使用指南

本项目是一个基于 Model Context Protocol (MCP) 的图片压缩服务器，使用 TinyPNG API 来优化图片。

功能特性

• ✅ 支持批量压缩目录中的所有图片
• ✅ 支持多种图片格式：.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"
      }
    }
  }
}

使用方法

可用工具

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%

支持的图片格式

根据 TinyPNG 官方文档，支持以下格式：

• PNG - 便携式网络图形
• JPEG/JPG - 联合图像专家组格式
• WebP - 现代网络图片格式
• AVIF - AV1 图像文件格式

限制说明

• 免费账户: 每月 500 次压缩
• 付费账户: 根据订阅计划不同
• 文件大小: 单个文件最大 5MB
• 并发请求: TinyPNG 有合理的速率限制

相关链接

• Model Context Protocol SDK
• TinyPNG API 文档