@tinify-dev/mcp

@tinify-dev/mcp

MCP (Model Context Protocol) server for the Tinify.dev image API. Lets Claude, Cursor, and any other MCP client compress, resize, crop, and convert local images — with honest results.

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.

• Never lies about savings — when the API cannot shrink a file it says so (optimized: false) instead of writing a byte-identical "optimized" copy.
• Never overwrites your originals silently — results go to <name>.min.<ext> beside the input, or to an explicit output_path. Replacing a file requires overwrite: true.
• Raw numbers in structuredContent on every call, so agents can do math instead of parsing prose.

Not affiliated with TinyPNG. This server talks to the Tinify.dev API.

Requirements

• Node.js >= 20
• A Tinify.dev API key from tinify.dev/developers — free tier is 500 operations/month, no card required.

Setup

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "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

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

Remote server (hosted)

The same five tools are available as a hosted streamable-HTTP MCP server - no install, works from ChatGPT connectors, the claude.ai directory, and any registry that expects a URL:

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

Two ways to authenticate:

• OAuth (for connectors) - ChatGPT connectors and the claude.ai directory only speak "OAuth" or "no auth". Add the server by its URL (https://api.tinify.dev/mcp) and pick OAuth; the client discovers the authorization and token endpoints automatically from the server's .well-known metadata, registers itself, and opens a Connect Tinify page where you paste your Tinify API key. Your key stays the credential - the client only ever holds an opaque token that maps back to it server-side.
• Direct bearer (for scripts/CLIs) - send Authorization: Bearer tnf_live_... (or tnf_test_...) and skip OAuth entirely. Unchanged.

Because the hosted server has no access to your filesystem, the image tools take base64 instead of paths: send image_base64 (optionally with filename), and the result comes back as base64 in structuredContent.image_base64 plus a text summary with byte counts. Inputs are capped at ~28 MB decoded (the 40 MB API limit minus base64 overhead); URLs are not accepted - the server never fetches remote content. get_usage is identical to the local version. Nothing is written to disk on either side.

Try it with 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"}}}'

For local files, prefer the stdio server above - it reads and writes them directly with no base64 round-trip and no 28 MB cap.

Tools

Tool	Arguments	Does
compress_image	path (absolute), output_path?, quality_mode? (balanced/best_quality/lossless), target_size_kb? (beta), overwrite?	Compresses PNG/JPEG/WebP/AVIF. Writes <name>.min.<ext> beside the input. When the API returns optimized: false, nothing is written (unless you asked for an explicit output_path).
resize_image	path, width?/height?/scale? (at least one), keep_aspect_ratio?, output_path?, overwrite?	Resizes and writes the result.
crop_image	path, x, y, width, height, output_path?, overwrite?	Crops to a rectangle and writes the result.
convert_image	path, format (avif/webp/jpeg/png), quality_mode?, output_path?, overwrite?	Converts formats (beta — the endpoint is rolling out server-side). Default output: <name>.min.<new-ext>.
get_usage	—	Plan, billing period, operations used and remaining.

All image tools require absolute paths (MCP servers run with an unpredictable working directory) and pre-check the 40 MB API limit locally. API errors come back as readable tool errors with the error code and request_id to quote to support.

Example prompts

• "Compress every PNG in /Users/me/site/static/img"
• "Resize /Users/me/photo.jpg to 1200px wide and tell me how many bytes it saved"
• "Convert /Users/me/hero.png to webp with best quality"
• "How many Tinify operations do I have left this month?"

Limits and privacy

• Max 40 MB / 50 MP per image; PNG, JPEG, WebP, AVIF.
• Uploaded images and results are deleted from Tinify.dev servers after 2 hours.
• The server only reads the files you point it at and only writes where it tells you it wrote.

Troubleshooting

• "TINIFY_API_KEY is not set" — the server exits at startup with the exact config snippet to fix it. Add the key to the env block of your MCP config.
• invalid_api_key — the key is wrong or revoked; create a new one at tinify.dev/developers.
• quota_exhausted (429) — the monthly quota is used up; run get_usage to see the period end.
• "path must be absolute" — pass full paths like /Users/you/img.png, not ./img.png.
• Logs go to stderr; in Claude Desktop see ~/Library/Logs/Claude/mcp-server-tinify.log.

Roadmap

• Batch tools (create/commit/wait/download) on top of the durable batch API — not in v1.

License

MIT © Stian Larsen

One-click / one-line installs

Cursor: Add to Cursor - then set your real key in Cursor's MCP settings.

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

or in ~/.codex/config.toml:

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

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

Claude Code plugin (MCP + image-optimization skill):

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

More: https://tinify.dev/mcp