---
name: image-optimizer
description: Turn a logo or photo into the lightest faithful web asset (traced SVG, or AVIF + WebP with responsive srcset), build favicon sets, and get the <img>/<picture> markup that keeps Lighthouse image audits green — via a remote MCP server or a REST API, nothing to install.
---

# image-optimizer

Use this when a site's images are costing Lighthouse points or load time: a PNG logo that should be
an SVG, a hero JPEG exported at 900 KB, a missing favicon set, or markup without `width`/`height`,
`srcset` or `fetchpriority`. Given a page rather than an image, run `image_audit` first: it lists every
image with what it costs on a phone and which fix applies, then convert the ones that matter.

## Connect

- MCP (stateless Streamable HTTP, keyless): `https://imageoptimizer.co/mcp`
  - Claude Code: `claude mcp add --transport http image-optimizer https://imageoptimizer.co/mcp`
  - `.mcp.json`: `{ "mcpServers": { "image-optimizer": { "type": "http", "url": "https://imageoptimizer.co/mcp" } } }`
- REST: `POST /api/v1/vectorize | /optimize | /favicons` (contract at `/api/v1/openapi.json`).
- Humans: the browser tool at `/convert/` (nothing uploaded).

## Tools

| Tool | When | Key arguments |
|---|---|---|
| `image_audit` | **Start here when given a page URL.** Fetches the public page, finds the images it serves (img and picture — where several sizes are offered, the candidate a phone would download, `phonePick`; CSS backgrounds set in the page's own styles, `kind: "css"`; og:image; up to 20) and reports per image: format, dimensions, bytes, markup findings with fixes (`unsized`, `lazy-lcp-risk`, `no-priority`, `no-srcset`, `legacy-format`, `vector-as-raster`, `oversized`, `css-background`), Slow 4G transfer time, share of the 2.5 s good-LCP budget and a labelled `est.` of what it would become. `summary.largest` is the LCP-shaped headline. Then convert the rows that matter with `image_optimize {image:{url}}` for real numbers; estimates are never measurements. One request, typically under a second. | `url` (https page, public hosts) |
| `image_analyze` | First look at one image: is it flat art or a photo? Cheap, no encoding. | `image: { url \| base64 }` |
| `image_optimize` | The default. Applies the decision rule, returns verdict + markup + load-time estimate; files as blobs with `return_base64: true`. | `mode`, `widths: "auto"` for heroes, `alt`, `lcp: true` for the above-the-fold image, `sizes` |
| `image_vectorize` | You know it is a logo/icon and want the SVG. | `preset: auto \| logo \| mono \| smooth \| poster \| detail`, `precision` |
| `image_favicons` | A site needs its icon set. | `name`, `themeColor`, `background` |
| `image_api_info` | Limits and defaults. | — |

Inputs: `image.url` must be `https://` on a public host (private, local and metadata addresses are
refused), ≤ 4.5 MB; or `image.base64` (data URLs accepted). Results above 4 MB inline → `isError`
`result_too_large`: call again with `return_base64: false` or fewer outputs.

## How it decides (AD_003)

Trace when the 16 most common colours cover ≥ 90 % of opaque pixels and there are ≤ 400 distinct
colours; keep the SVG when PSNR ≥ 22 dB, SSIM ≥ 0.93, at most 8 % of detailed regions are damaged
(text and thin strokes), and it is no larger than the AVIF. Otherwise AVIF q45 + WebP q75 + a fallback.
Transparent multi-colour logos are flattened, traced in cutout mode and made transparent again.

## What to do with the result

1. Write the files next to the page; name them as in `structuredContent.files`.
2. Paste `structuredContent.markup` as is — it already carries `width`/`height`, `decoding`,
   `fetchpriority="high"` for the LCP image, `loading="lazy"` otherwise, and `srcset`/`sizes` when
   widths were requested.
3. Serve with `Cache-Control: public, max-age=31536000, immutable` and the right `Content-Type`
   (`image/svg+xml`, `image/avif`, `image/webp`).
4. Quote `structuredContent.speed`: the per-request transfer time on Lighthouse's Slow 4G profile
   (150 ms RTT + bytes at 1.6 Mbps) before and after — the number the site owner understands.

## Limits

Public quota: 20 requests/s across all callers, no key; per client IP, 30 tool calls and 300 requests per 5 minutes (a 429 carries a JSON-RPC error with `data.retry_after: 300` — wait, do not retry in a loop). Inputs ≤ 4.5 MB (the browser tool has no
limit). Hero images with `widths: "auto"` take 10–20 s. Source and field tests:
https://imageoptimizer.co/research/famous-logos/ and https://imageoptimizer.co/research/hero-images/ (noindex pages on this site).