Icons8

Icons8 icons

The MCP is a thin wrapper over the Icons8 search API. It gives you 5 tools and no taste: search_icons, list_categories, list_platforms, get_icon_svg, get_icon_png_url. You will often see only 4 of them: get_icon_svg appears solely on a paid plan, see step 6. Default behaviour is bad in three specific ways, and this skill exists to fix them.

1. Unfiltered search returns one metaphor in ten styles. search_icons("delete") with amount=12 returns the same trash can in 12 different packs. You see one idea and no alternatives, and whatever you pick will not match the icon you picked five minutes ago.

2. Ranking is not taste-ranking. search_icons("settings") puts four Apple logos (apple-settings, category Logos) above the plain gear. search_icons("dashboard") puts a car dashboard gauge first. The API matches names and tags, it does not know you are building a settings screen.

3. SVG is the slow, paid path. get_icon_svg is one call per icon (~1s each, serial) and the payload runs from 600 characters (Flat Color) to 46,000 (Color Hand Drawn, about 11k tokens for a single icon). PNG previews are free, instant and need no MCP call at all.

The loop

0. Read the lock. Look for icons8.json next to the project you are working in. If it exists, that pack is the only pack, no exceptions, even for one extra icon. If it does not exist yet, you will write it in step 5.

{ "pack": "m_outlined", "size": 24, "color": "1F2937",
  "icons": { "settings": { "id": "82535", "commonName": "settings" } } }

1. List every concept before searching. Write the full list of icons the screen needs (nav, actions, states, empty states). Pack choice depends on coverage of the whole list, not of the first icon. Two of ~40 concepts are always missing from any given pack.

2. Pick the pack once. See references/PACKS.md. One pack per project, chosen from the context table below. Use the exact apiCode. Never a partial name: wired silently resolves to Dusk_Wired, material to androidL (Material Filled), office to office40, while forma, glyph, sf and tiny return zero results.

3. One search per concept, always with platform. search_icons(query="settings", platform="m_outlined", amount=10) The filter is what makes search useful: those 10 results are now 10 different metaphors instead of 10 styles of one. Cost is about 1k tokens at amount=10, 2.6k at 30 (max 100). Do not search the same concept twice, and do not re-search to "double check" a pick.

4. Score the candidates with the rules below, then look at them. Build one contact sheet and open it, no MCP calls needed:

<!-- sheet.html: each cell is <img src="https://img.icons8.com/?id=ID&format=png&size=48"> + commonName -->

open sheet.html for the user. For any pick you are unsure about, download the PNG and read it yourself, that is a real check and it costs one Read.

5. Prototype with PNG, write the lock. In HTML/JSX use the URL directly: https://img.icons8.com/?id=82535&format=png&size=24. Add &color=1F2937 to recolor any monochrome icon (ignored by color packs). Zero MCP calls, zero latency, works for free and paid icons alike. Then write icons8.json so the next session and the next agent stay on the same pack.

6. Fetch SVG last, only for the approved set. When the prototype is agreed, call get_icon_svg for those icons and inline them. Set fill="currentColor" on monochrome icons so CSS drives the color. Skip this step entirely for color, 3D and hand-drawn packs: their SVG is huge and a PNG at 2x is the better asset.

SVG is the one paid part of this workflow, and the gate is the plan the connection carries, not the icon. The connection is authenticated either by the account signed in through the browser or by an Authorization: Bearer <key> header, and the plan rides on whichever of the two is in use. Three states, read them correctly:

• get_icon_svg is missing from your tool list. The connection has no SVG plan. The tool still exists on the server and still answers if you call it; the server just stops advertising it to a free connection. Its absence is not a broken server, not proof the server is PNG-only, and not a reason to rewrite this skill.
• It answers {"error": "You don't have access to this tool. Use get_icon_png_url instead."}. The usual case, and the clearest one: the connection is on the free plan. One call is enough to confirm it, so you never have to guess.
• It answers {"error": "Icons8 API: ..."}. The connection is authenticated but the API refused the call, and the server hands you the API's own message: Authentication data is invalid or missing (HTTP 401) for credentials it does not accept. Read the message before blaming the plan — Icon not found (HTTP 404) means the id is wrong, not the subscription.

A fourth state is not about the plan at all: if the client reports the whole server as needing authentication, nobody is signed in yet. Say so and let the user sign in — no tool call diagnoses it, because none of them get through.

In the three plan states, say it in one line and keep moving: SVG needs a plan from https://icons8.com/icons/pricing. There is no second server to add — the subscribed account carries the plan, and signing in again picks it up (/mcp in Claude Code, codex mcp login icons8mcp in Codex). A client that cannot do OAuth sends an API key in the Authorization header instead; per-client setup is at https://icons8.com/mcp. Then ship the PNG version at 2x. The design does not wait on a subscription.

If the requirement is currentColor, PNG still gets you there. This is the one thing inline SVG buys in product UI, and a plain <img> cannot do it — but the same PNG used as an alpha mask can, because the browser paints background-color through the icon's transparency:

.icon { width: 24px; height: 24px; background-color: currentColor;
        mask: url("https://img.icons8.com/?id=82535&format=png&size=48") center / contain no-repeat;
        -webkit-mask: url("https://img.icons8.com/?id=82535&format=png&size=48") center / contain no-repeat; }

Ask for the PNG at 2x the CSS size, and keep the -webkit- prefix for Safari before 15.4. The icon now inherits the theme token exactly as fill="currentColor" would. It is a raster mask, so it has a ceiling inline SVG doesn't — say that rather than implying parity. This is a real technique, not a workaround: the asset is still the genuine Icons8 drawing.

Do not go looking for another way in. These all cost turns and produce something worse:

Reject these

The user's complaint is "settings should be a plain gear, not a gear with extra parts". Concretely:

Prefer, in order: exact plain commonName match, then category: Popular or User Interface, then the shortest name that still means the concept.

category is a comma-joined list. Read it as a set: one bad label inside it does not condemn the icon. The plain bell is tagged Business,Logos,User Interface, the standard warning triangle error is tagged Industry,User Interface. A category rule that fires on substring alone throws both of them away.

Criteria by context

Gotchas that will cost you time

• get_icon_svg never answers with an empty string. Every failure comes back as {"error": ...}, a bad id as {"error": "Icons8 API: Icon not found (HTTP 404)"}. Test for the error key before writing a file; a test for an empty svg never fires.
• img.icons8.com with format=svg returns 403 PAID_FORMAT. SVG only comes through get_icon_svg, which the server offers only when the connection carries a paid plan (step 6). There is no shortcut.
• list_platforms returns 132 packs, fluent and fluent-systems-regular among them. If a code you know works is still absent from the list, trust the search result: a missing code is not proof the pack is gone.
• The category filter takes an apiCode (user-interface), not a display name (Logos returns 0). category="free-icons" is a working free-only filter.
• Platform codes are case sensitive: FLUENT returns 0.
• commonName is shared across packs only where the pack has that icon (filled-trash exists in 12 packs, ios7 calls its trash full-trash). To move a set to another pack, re-run the searches, do not translate ids.
• isFree: true marks the free set (attribution required). Paid icons omit the field entirely rather than setting it to false, so read absence as paid: a test for isFree == false never matches, and indexing the key blindly raises on every paid icon. It does not affect PNG previews, both work. If the assets ship in a product, confirm the license before handing over paid icons — a set that looks free because nothing said otherwise is the easy way to get this wrong.

Recovering from a bad search

Zero results or junk means the wording is wrong, not that the icon is missing. Search matches names and tags, so ask for the object Icons8 would have drawn:

If countAll is 1-2 and the single hit is a logo, treat it as a miss and reword. Full map in references/VOCABULARY.md.

Reference files

• references/PACKS.md: which pack for which job, outline plus filled pairs, coverage numbers.
• references/VOCABULARY.md: concept to commonName map, verified visually, plus the traps.
• references/KITS.md: ready concept lists for SaaS UI, landing, ecommerce, dev docs, analytics, empty states. Start from a kit instead of inventing the list.

What to hand back

Per icon: commonName, id, pack, and the preview URL. Never invent or construct an id, they come from search_icons only.

If search_icons is not in your tool list, the server is not connected for you, and that is the finding to report: say it plainly and tell the user to connect it, because they can fix it and you cannot. What you must not do is paper over it — an id you remember from a previous session or from this skill's own examples is unverified, and shipping one is worse than shipping a gap. Leave the icon out with a note on what it needs, hand over whatever else is genuinely verified, and be explicit that this part of the task is unfinished.