---
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 whole brand kits (logo lockups, og image, social and marketing sizes, press page — from a logo or just a name), 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; `GET /mcp` is the info document with `auth` + `connect`): `https://d33mzu51alopvl.cloudfront.net/mcp`
  - With an ImageOptimizer account: send the API key as `Authorization: Bearer io_…` — `image_vectorize`, `image_optimize` and `image_favicons` then count on that plan instead of the shared per-IP quota. A bad or exhausted key comes back as a tool result with `isError: true` and a `hint`; read it to the user, do not retry.
  - Claude Code: `claude mcp add --transport http image-optimizer https://d33mzu51alopvl.cloudfront.net/mcp`
  - `.mcp.json`: `{ "mcpServers": { "image-optimizer": { "type": "http", "url": "https://d33mzu51alopvl.cloudfront.net/mcp" } } }`
- REST: `POST /api/v1/vectorize | /optimize | /favicons | /brand-kit` (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. SVG input is passed through as `favicon.svg`. | `name`, `themeColor`, `background` |
| `image_brand_kit` | A site or product needs its icons **and** its logo at every size: lockups (mark, wordmark, horizontal, stacked; SVG + PNG 1x/2x/4x; brand/black/white), `og.png` 1200×630, square post, avatars 400/1024, X/LinkedIn/YouTube/email banners, press logos, `brand/index.html` press page, `head.html` with icon + og:image lines. With `image` the logo is the mark; without it a monogram tile + wordmark are drawn from `name` in a shipped font. Drop the zip (`POST /api/v1/brand-kit?format=zip`) into the site root. 45–70 files: use `return_base64: false` for the listing, then fetch the zip over REST. | `name` (required), `image` (optional, SVG ok), `monogram`, `tagline`, `font: permanent-marker \| poppins \| archivo-black \| lobster \| pacifico \| bangers`, `colour`, `background`, `origin` (site https origin for absolute og:image) |
| `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 (`rate-mcp`) and 300 requests (`rate-mcp-all`) 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://d33mzu51alopvl.cloudfront.net/research/famous-logos/ and https://d33mzu51alopvl.cloudfront.net/research/hero-images/ (noindex pages on this site).
