MCP integration guide

Let your AI agent compress images: MCP explained

Connect Claude or Cursor to the Tinify.dev API over MCP: setup snippets, the five tools, real costs, and the never-overwrite-source design.

Updated July 24, 2026 by Tinify.dev

If you work with an AI coding assistant, some image tasks fit it naturally: "compress every screenshot in this folder", "resize the hero image to 1200px and tell me what it saved", "convert these PNGs to WebP before I commit". The assistant can already read your files and run your tools - what it needs is a safe way to call an image API. That is what our MCP server provides.

One paragraph on MCP, without evangelism: the Model Context Protocol is an open standard for connecting AI assistants to external tools. A small local program (a "server") describes its tools to the assistant - names, arguments, what they do - and the assistant calls them when a task fits. Claude Desktop, Claude Code, and Cursor all speak it, along with a growing list of other clients. That is all the theory this article needs.

If you just want the install command for your client, the Tinify MCP page collects every path - Claude Code, Claude Desktop, Cursor, VS Code, and Codex - on one page.

What the server does

@tinify-dev/mcp (source) exposes five tools backed by the Tinify.dev API:

Tool	What it does
`compress_image`	Compresses PNG/JPEG/WebP/AVIF; supports quality modes and a target size
`resize_image`	Resizes by width, height, or scale
`crop_image`	Crops to a rectangle
`convert_image`	Converts between AVIF, WebP, JPEG, and PNG
`get_usage`	Reports plan, billing period, and operations used and remaining

Every image tool returns raw numbers in structured content - original bytes, result bytes, the path written - so the agent can do arithmetic instead of parsing prose.

Setup

You need Node.js 20 or newer and an API key from tinify.dev/developers - free, no card, 500 operations per month.

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 - one command:

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_..." }
    }
  }
}

After a restart, prompts like "compress every PNG in /Users/me/site/img" resolve to tool calls.

The design decision that matters: never overwrite silently

An agent editing files on your disk deserves more suspicion than a person doing the same thing, because it acts faster and you review later. The server is built around that:

Results are written beside the input as <name>.min.<ext> - your original stays untouched by default.
Replacing a file requires overwrite: true, an explicit argument the agent has to choose. "Compress this" never destroys the only copy.
When compression saves nothing, no file is written. The API reports optimized: false rather than producing a byte-identical "optimized" copy, and the tool passes that honesty through. Your agent will tell you a logo is already as small as it gets instead of claiming imaginary savings.
Absolute paths are required. MCP servers run with an unpredictable working directory; refusing relative paths eliminates a whole class of "it wrote the file where?" surprises.

The 40 MB API limit is checked locally before upload, and API errors surface with their error code and request ID rather than a generic failure.

What it costs to run

Nothing hidden, but not nothing:

Every compress, resize, crop, and convert call is one API operation against your quota. The free tier includes 500 per month; paid plans are $9/month for 2,000 and $29/month for 10,000 - see the pricing page.
An agent told to "optimize all images in the project" on a large repo will happily spend hundreds of operations. Ask get_usage first - "how many Tinify operations do I have left?" - or scope the prompt to a directory.
Images are uploaded to Tinify.dev for processing and deleted after two hours. If a file must never leave your machine, do not point any cloud-backed tool at it, ours included.

Where this fits, and where it does not

The MCP server is the right tool when image work happens inside a conversation: cleaning up assets during a refactor, preparing screenshots while writing docs, one-off conversions mid-task. It is the wrong tool for recurring pipeline work - a CI action does that without burning agent context, and the web compressor is faster for a folder of files you can drag into a browser.

Batch operations on the durable batch API are on the roadmap but not in v1; today the server processes one file per tool call, which in practice is what agent workflows do anyway.

If you try it and something is unclear or wrong, the issue tracker is open. It is version 0.x software talking to a stable API - the API side is boring on purpose; the MCP side is young and we would rather hear about rough edges than guess.