@tinify-ai/mcp-server

@tinify-ai/mcp-server

MCP server for tinify.ai image optimization. AI-powered upscaling, resizing/cropping, compression, and SEO tag generation — all in one tool.

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-ai/mcp-server@latest"]
    }
  }
}

No signup required. Works out of the box with 20 free daily credits.

Client-Specific Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-ai/mcp-server@latest"]
    }
  }
}

Claude Code

claude mcp add tinify -- npx -y @tinify-ai/mcp-server@latest

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-ai/mcp-server@latest"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "tinify": {
      "command": "npx",
      "args": ["-y", "@tinify-ai/mcp-server@latest"]
    }
  }
}

Tool: optimize_image

Optimizes an image with smart lossy compression (typically 60-80% size reduction), optional resize/upscale/format conversion, and AI-generated SEO metadata. Accepts absolute local file paths or remote URLs.

Parameters

Parameter	Type	Required	Default	Description
input	string	Yes	—	Absolute local file path or remote URL
output_path	string	No	auto	File path or directory (ending in /). If omitted: saves next to original with SEO slug or .tinified suffix
output_format	string	No	original	jpeg, png, webp, or original
output_width_px	int	No	—	Target width in pixels
output_height_px	int	No	—	Target height in pixels
output_upscale_factor	float	No	—	AI upscale factor (e.g. 2.0, 4.0)
output_resize_mode	string	No	pad	pad (white padding) or crop (smart crop). Only used when both width and height are set
output_seo_tag_gen	bool	No	true	Generate SEO metadata and rename file to SEO slug. Costs 1 extra credit

Resize Behavior

Dimensions provided	Behavior	output_resize_mode
Width only	Proportional scale	N/A
Height only	Proportional scale	N/A
Width + Height	Exact dimensions, white padding	pad (default)
Width + Height	Exact dimensions, smart crop	crop

Examples

Basic compression — just compress, keep format and dimensions:

{ "input": "/Users/me/photos/hero.png" }

Convert to WebP:

{ "input": "/Users/me/hero.png", "output_format": "webp" }

Resize proportionally — set one dimension, the other scales:

{ "input": "/Users/me/hero.png", "output_width_px": 1200 }

Exact dimensions with padding — white bars fill the gap:

{ "input": "/Users/me/hero.png", "output_width_px": 1080, "output_height_px": 1080 }

Exact dimensions with smart crop:

{ "input": "/Users/me/hero.png", "output_width_px": 1080, "output_height_px": 1080, "output_resize_mode": "crop" }

AI upscale 4x:

{ "input": "/Users/me/icon.png", "output_upscale_factor": 4 }

From URL, save to directory:

{ "input": "https://example.com/photo.jpg", "output_path": "/Users/me/assets/" }

Skip SEO to save 1 credit:

{ "input": "/Users/me/hero.png", "output_seo_tag_gen": false }

Output

Returns a text summary and structured metadata:

Optimized: /Users/me/photos/modern-office-workspace.webp
Size: 142.3 KB
Compression: 73%
Format: webp
Dimensions: 1920x1080
Alt text: Modern office workspace with laptop and coffee cup on wooden desk

Structured output fields:

{
  "output_path": "/Users/me/photos/modern-office-workspace.webp",
  "output_size_bytes": 145715,
  "output_width_px": 1920,
  "output_height_px": 1080,
  "output_format": "webp",
  "compression_ratio": 0.27,
  "seo_alt_text": "Modern office workspace with laptop and coffee cup on wooden desk",
  "seo_keywords": ["office", "workspace", "laptop", "desk", "modern"],
  "seo_filename": "modern-office-workspace"
}

Supported Formats

Format	Input	Output
JPG	Yes	Yes
PNG	Yes	Yes
WebP	Yes	Yes
AVIF	Yes	Yes
HEIC/HEIF	Yes*	No
TIFF	Yes*	No
BMP	Yes*	No

*Automatically converted to JPG at upload time.

Max file size: 50 MB.

How It Works

Local file or URL
  → Upload to Tinify API
    → Smart compression (lossy, typically 60-80% reduction)
    → AI SEO tag generation (alt text, keywords, filename)
    → Optional: resize, upscale, format conversion
  → Download optimized file
    → Save with SEO filename slug (or .tinified suffix if SEO disabled)

All processing happens server-side via the Tinify API. The MCP server is a thin client that orchestrates the pipeline.

Credits

	Free Tier
Credits/day	20
Images/day	~5 (with default settings)
Cost per image	3 credits + 1 if SEO tags enabled (default)
Signup required	No

Session tokens are stored locally at ~/.tinify/session.json and persist across invocations.

Need more credits? See plans at tinify.ai.

Tips for AI Agents

Paste this into your CLAUDE.md or system prompt to help agents use the tool effectively:

## Tinify MCP — optimize_image

- Each call costs 3 credits + 1 if SEO enabled (default). Free tier: 20 credits/day.
- Always use absolute file paths, not relative.
- Set only width OR height for proportional resize. Set both for exact dimensions.
- When both dimensions are set, use output_resize_mode: "crop" for photos, "pad" for logos/icons.
- output_seo_tag_gen (default true) renames the file to an SEO slug and generates alt text + keywords.
- Set output_seo_tag_gen: false to save 1 credit when SEO metadata is not needed.
- HEIC, TIFF, BMP inputs are auto-converted to JPG.
- For batch processing, call optimize_image once per file.

Troubleshooting

Server not appearing in tool list:

• Restart your MCP client after editing the config
• Ensure Node.js >= 18 is installed: node --version
• Try running directly: npx -y @tinify-ai/mcp-server@latest (should start without errors)

"Insufficient credits" error:

• Free tier allows 20 credits/day (resets daily)
• Each image costs 3-4 credits depending on settings
• Disable SEO tags (output_seo_tag_gen: false) to reduce to 3 credits/image

File not found:

• Use absolute paths for local files
• For URLs, ensure the image is publicly accessible

Timeout errors:

• Large images or AI upscaling can take 30-60 seconds
• The server has a 60-second timeout per job

Requirements

• Node.js >= 18
• An MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, etc.)

License

MIT - see LICENSE.