Tinify image tools

@tinify-dev/mcp

适用于 Tinify.dev 图像 API 的 MCP（Model Context Protocol）服务。让 ChatGPT、Claude、Cursor 和其他 MCP 客户端能够压缩、调整尺寸、裁剪和转换图像，并如实报告结果。

You: compress the screenshots in ~/Desktop/launch/
Claude: 312.4 KB → 97.1 KB (-68.9%), wrote /Users/you/Desktop/launch/hero.min.png
        84.2 KB → 84.2 KB — logo.png is already as small as Tinify.dev can make it
        (optimized: false), so no file was written.

• 绝不谎报节省量——如果 API 无法缩小文件，就会如实说明（optimized: false），而不是写入一个字节完全相同的“优化”副本。
• 绝不悄悄覆盖原文件——结果会保存到输入文件旁的 <name>.min.<ext>，或指定的 output_path。只有设置 overwrite: true 才会替换文件。
• 每次调用都会在 structuredContent 中返回原始数值，这样 Agent 可以直接进行计算，而不必解析文字。

与 TinyPNG 没有关联。本服务连接的是 Tinify.dev API。

要求

• Node.js >= 20
• Tinify.dev API 密钥，可从 tinify.dev/developers 获取——免费套餐每月可进行 500 次操作，无需信用卡。

设置

Claude Desktop

添加到 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-dev/mcp"],
      "env": { "TINIFY_API_KEY": "tnf_live_..." }
    }
  }
}

Claude Code

claude mcp add tinify -e TINIFY_API_KEY=tnf_live_... -- npx -y @tinify-dev/mcp

Cursor

在项目中创建 .cursor/mcp.json（或在全局路径 ~/.cursor/mcp.json 中创建）：

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-dev/mcp"],
      "env": { "TINIFY_API_KEY": "tnf_live_..." }
    }
  }
}

远程服务（托管）

相同的五个工具也可通过托管的可流式传输 HTTP MCP 服务使用——无需安装，可用于 ChatGPT 连接器、claude.ai 目录，以及任何需要 URL 的注册表：

Endpoint:  https://api.tinify.dev/mcp
Auth:      OAuth 2.1 (PKCE + dynamic client registration), or
           Authorization: Bearer tnf_live_...   (or tnf_test_...)

有两种身份验证方式：

• OAuth（适用于连接器）——ChatGPT 连接器和 claude.ai 目录只支持“OAuth”或“无身份验证”。使用服务器 URL（https://api.tinify.dev/mcp）添加服务，并选择 OAuth；客户端会通过服务的 .well-known 元数据自动发现授权端点和令牌端点、完成自身注册，并打开 Connect Tinify 页面，供你粘贴 Tinify API 密钥。你的密钥仍是凭据——客户端只会持有一个不透明令牌，该令牌在服务端映射回你的密钥。
• 直接承载令牌（适用于脚本/命令行工具）——发送 Authorization: Bearer tnf_live_...（或 tnf_test_...），即可完全跳过 OAuth。保持不变。

ChatGPT 开发者模式连接

1. 在 ChatGPT 中，打开 设置 → 安全和登录，启用 开发者模式。

2. 打开 ChatGPT Plugins，选择加号按钮，然后添加 https://api.tinify.dev/mcp。

3. 使用 Tinify API 密钥完成 Connect Tinify。

4. 从对话的工具菜单中添加此连接，附加一张 PNG/JPEG/WebP/AVIF 图像，然后提出以下请求：

   Use Tinify to compress this image for the web. Show the original size,
   result size, and percentage saved.
   

托管服务无法访问本地路径，因此每个图像工具只接受以下其中一种输入：

• image——ChatGPT 附件对象。由于描述符声明了 openai/fileParams，ChatGPT 会自动填充此参数。
• image_base64——供其他 MCP 客户端使用的可移植备用方案，解码后大小上限约为 28 MB。

ChatGPT 附件下载仅支持 HTTPS，会拒绝私有/保留网络目标和重定向，超时时间为 30 秒，且大小上限为 Tinify API 的 40 MB。操作成功后会返回精确的字节指标和临时 MCP 结果链接。为保持向后兼容，现有 base64 调用方也会收到 structuredContent.image_base64。get_usage 与本地版本完全相同。不会向用户的文件系统写入任何内容。

使用 curl 试试：

curl -s https://api.tinify.dev/mcp \
  -H "Authorization: Bearer tnf_live_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

对于本地文件，建议使用上面的 stdio 服务——它可以直接读取和写入文件，无需进行 base64 往返转换，也没有 28 MB 的大小限制。

一个服务，两种传输适配器

此仓库有意同时支持 OpenAI 和 Claude：

• 共用的工具名称、Tinify 客户端、结果指标、错误和注释与平台无关。
• stdio 适配器使用本地绝对路径，并为 Claude、Cursor 和 Codex 等桌面端／命令行客户端写入文件。
• 托管适配器使用 ChatGPT 文件附件或 base64，并返回临时结果链接，因为托管服务无法读取用户的文件系统。

仅支持 OpenAI 的仓库会重复 Tinify 逻辑，也更容易导致行为不一致。OpenAI 专属描述符元数据作为一个小型附加层保留在托管适配器中；无需单独建立仓库。

如需公开提交至 OpenAI，请将门户提供的域名令牌设为 OPENAI_APPS_CHALLENGE_TOKEN，写入 /etc/tinify/mcp-http.env，并部署 deploy/nginx-location.conf 中对应的 nginx location。该端点只会在 /.well-known/openai-apps-challenge 返回此令牌；请勿提交真实的门户令牌。

工具

工具	参数	功能
compress_image	path（绝对路径）、output_path?、quality_mode?（balanced/best_quality/lossless）、target_size_kb?（测试版）、overwrite?	压缩 PNG/JPEG/WebP/AVIF。将文件写入输入文件所在目录，命名为 <name>.min.<ext>。当 API 返回 optimized: false 时，不会写入任何文件（除非你指定了明确的 output_path）。
resize_image	path、width?/height?/scale?（至少指定一项）、keep_aspect_ratio?、output_path?、overwrite?	调整图像尺寸并写入结果。
crop_image	path、x、y、width、height、output_path?、overwrite?	裁剪为矩形并写入结果。
convert_image	path、format（avif/webp/jpeg/png）、quality_mode?、output_path?、overwrite?	转换格式（测试版——该端点正在逐步推出服务端支持）。默认输出：<name>.min.<new-ext>。
get_usage	—	查看套餐、计费周期、已用和剩余操作次数。

所有图像工具都要求使用绝对路径（MCP 服务的工作目录不可预测），并会在本地预先检查 40 MB 的 API 限制。API 错误会以易读的工具错误形式返回，其中包含可提供给支持团队的错误 code 和 request_id。

提示词示例

• “压缩 /Users/me/site/static/img 中的所有 PNG”
• “将 /Users/me/photo.jpg 调整为 1200px 宽，并告诉我节省了多少字节”
• “以最佳质量将 /Users/me/hero.png 转换为 webp”
• “我这个月还剩多少次 Tinify 操作？”

限制与隐私

• 每张图像最大 40 MB / 50 MP；支持 PNG、JPEG、WebP、AVIF。
• 上传的图像和结果会在 2 小时后从 Tinify.dev 服务器删除。
• 服务只会读取你指定的文件，并且只会写入它告知你的目标位置。

故障排查

• “TINIFY_API_KEY is not set” — 服务启动时会退出，并显示需要修复的准确配置代码段。将密钥添加到 MCP 配置的 env 块中。
• invalid_api_key — 密钥错误或已撤销；请在 tinify.dev/developers 创建新密钥。
• quota_exhausted (429) — 月度配额已用尽；运行 get_usage 查看周期结束时间。
• “path must be absolute” — 请传入 /Users/you/img.png 这样的完整路径，而不是 ./img.png。
• 日志写入 stderr；在 Claude Desktop 中查看 ~/Library/Logs/Claude/mcp-server-tinify.log。

路线图

• 基于持久化批处理 API 提供批处理工具（create/commit/wait/download）——不包含在 v1 中。

许可证

MIT © Stian Larsen

一键／单行安装

Cursor：添加到 Cursor - 然后在 Cursor 的 MCP 设置中设置你的真实密钥。

VS Code：

code --add-mcp '{"name":"tinify","command":"npx","args":["-y","@tinify-dev/mcp"],"env":{"TINIFY_API_KEY":"tnf_live_..."}}'

Codex CLI：

codex mcp add tinify --env TINIFY_API_KEY=tnf_live_... -- npx -y @tinify-dev/mcp

或在 ~/.codex/config.toml 中：

[mcp_servers.tinify]
command = "npx"
args = ["-y", "@tinify-dev/mcp"]

[mcp_servers.tinify.env]
TINIFY_API_KEY = "tnf_live_..."

Claude Code 插件（MCP + 图像优化技能）：

/plugin marketplace add Stianlars1/tinify-claude-plugin
/plugin install tinify@tinify

更多信息：https://tinify.dev/mcp