# Icons8 MCP

> An MCP server that searches and retrieves genuine Icons8 icons and Ouch
> illustrations - SVG, PNG and animation - for agents filling in UI, decks,
> docs, or anywhere that needs real artwork instead of an emoji or a
> placeholder.

## Connecting

See [`/auth.md`](/auth.md) for the full authentication recipe: OAuth - the client identifies itself with a Client ID Metadata Document or registers with Dynamic Client Registration, then a human signs in to Icons8, or a personal API key pasted by hand with no registration at all. A request with neither gets a 401 carrying `WWW-Authenticate`, which is where that recipe starts.

## Tools

Two sets, one per kind of artwork. Icons are small symbols; illustrations are full scenes. Picking the wrong set is the most common way to get artwork that does not fit the slot it was asked for.

### Icons - for buttons, menus, toolbars and tables

- `search_icons`: search the Icons8 catalog by keyword, with metaphor-aware search tips. `animated=True` narrows to the icons that move; each of those carries permanent `animation.gif` and `animation.apng` links that need no credential.
- `list_categories`: list icon categories, paginated.
- `list_platforms`: list icon platforms/styles (iOS, Fluent, Color, and more), paginated.
- `get_icon_svg`: fetch an icon as SVG, the preferred format. Needs an Icons8 plan with MCP access, through a sign-in or a personal key.
- `get_icon_png_url`: build a PNG preview URL for an icon (24x24 by default).
- `get_icon_animation`: get an animated icon's motion - `lottie` returns the Lottie/Bodymovin animation as a compact JSON string and needs a plan with MCP access, `gif` and `apng` return a permanent URL and need none. gif and apng come only in the size the icon's style draws at - call it without a size and the result says which; name one only to check it, because a size the icon is not drawn at is refused and Lottie is what scales. Only for an icon whose search result says `isAnimated`. There is no animated SVG.

### Illustrations - for hero images, empty states and onboarding

- `search_illustrations`: search the Ouch catalogue by keyword. Every hit carries a permanent preview link, for choosing and for mock-ups: clean for a free hit (`free_distribution: true`) and for a sign-in whose plan covers illustrations, watermarked ("Icons8 Ouch") otherwise. To publish, download the file: a standard PNG needs no plan.
- `list_illustrations_categories`: list illustration categories, paginated.
- `list_illustrations_styles`: list illustration styles - the visual-family axis, the illustration counterpart of an icon platform. Keep one style across a project.
- `get_illustration_svg`: build a presigned SVG download URL - a link, not the file, which for an illustration is too large to return as text.
- `get_illustration_png_url`: build a presigned PNG download URL, in three sizes.
- `get_illustration_animation`: build a presigned download URL for an animated illustration - WebM, HEVC .mp4, ProRes, GIF, Lottie or the After Effects project. An animated search hit carries `animation.webm` and `animation.mov` previews - 368px, no transparency, watermarked unless `animation.watermarked` says false - for choosing. This tool returns the file to publish; offer both in one `<video>`, since WebM covers Chrome and Firefox and HEVC covers Safari.

The illustration download URLs are presigned and expire in one hour. The permanent link to an illustration is the preview already carried in a search result - a preview, not the file.

### Your account

- `account_info`: show the caller's Icons8 account - plan, how many icon SVG, Lottie and paid illustration downloads are left, when the allowance renews, and this server's own limit on paid downloads. It takes no download and changes no plan. After an Icons8 sign-in it shows all of that; an account whose plan has no MCP access gets the plan and the free formats instead, and no limit unless it holds paid illustrations. A personal key pasted by hand shows the account only when it also signed in here, and otherwise says to connect through the sign-in.

A credential is required to connect at all: either an Icons8 sign-in through OAuth, or a personal key in an `Authorization: Bearer` header (see `/auth.md`). Most tools work once connected. Two need an Icons8 plan with MCP access behind that credential: `get_icon_svg`, which stays hidden from `tools/list` until a credential is present, and `get_icon_animation` with `format="lottie"` - its `gif` and `apng` need nothing. An illustration's SVG, HD PNG and every animation format but `gif-low` need a sign-in - a personal key does not reach them - whose plan covers illustrations and MCP access, unless the hit says `free_distribution: true`. Plans: https://icons8.com/pricing?utm_source=mcp.

Paid formats are limited to 100 per hour and 1000 per day per account, icons and illustrations together: `get_icon_svg`, `get_icon_animation` with `format="lottie"`, `get_illustration_svg`, `get_illustration_png_url` with `size="hd"`, and `get_illustration_animation` in any format but `gif-low`. A refused call answers with `retry_after_seconds` and names the free format that still works.

`get_icon_svg` and `get_icon_animation` with `format="lottie"` have a second refusal. When the plan's download allowance is spent, or the plan has none, they answer with `code` `limit_exhausted`: a free 24px PNG in `url` for `get_icon_svg`, the gif and apng links in `animation` for the Lottie. Each tool has its own allowance, so a refusal of one says nothing about the other. Until that tool's allowance changes or renews, it refuses every icon (`get_icon_svg` still serves one the account downloaded before); `get_icon_png_url` still works. If the user says they upgraded their plan or the allowance renewed, call the refused tool again.

## Skills

The tools above are a thin wrapper over a search API; they have no taste. [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json) lists the skills that supply it: `icons8` for symbols - how to pick one icon pack and stay on it, which metaphors to reject, when to prefer a PNG preview over an SVG - and `ouch` for full illustrations. Seven more check the screen built with them: `icons8-design` routes a design pass to `asset-check`, `ux-check`, `ux-writing`, `ui-polish`, `motion`, `design-tokens` or `illustration-animator`, and merges their findings into one report. `illustration-animator` turns static SVG illustrations into looped Lottie, GIF and MOV, and on macOS an MP4.
