@saastemly/iconify-mcp

A local, fully-offline MCP server that gives AI agents fast, intuitive access to every Iconify icon — ~312,000 icons across 214 sets — with keyword search, style/variant awareness, and on-demand SVG rendering.

It ships a prebuilt SQLite + FTS5 index of the entire @iconify/json bundle inside the package, searches it in-process, and renders any icon to SVG with @iconify/utils. No network. No Iconify API. No API key. After the one-time npx download it works completely offline.

Runs on plain Node ≥20 — no Bun, no Python, no build step required.

Quick start (npx)

Add it to any MCP client. The first run downloads the package (which includes the icon index) and the native SQLite dependency; every run after that is offline.

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "iconify": {
      "command": "npx",
      "args": ["-y", "@saastemly/iconify-mcp"]
    }
  }
}

Claude Code CLI:

claude mcp add iconify -- npx -y @saastemly/iconify-mcp

Cursor / Windsurf / any MCP client — same idea: command npx, args ["-y", "@saastemly/iconify-mcp"].

Prefer a pinned global install? npm i -g @saastemly/iconify-mcp then use the iconify-mcp command directly.

Requirements: Node ≥ 20. The package bundles the ~120 MB SQLite index, so the first npx fetch is a sizeable one-time download; it's cached by npm afterwards.

Tools

| Tool | What it's for | |---|---| | search_icons | Fuzzy keyword search across all sets. Scope inline (lucide:home / lucide home) or via prefix; filter by style, category, palette; prefer a set. Mainstream sets are surfaced first. | | get_icon | Render one icon to SVG (aliases/transforms resolved). Optional color, width/height, data_url. Returns ready-to-paste usage snippets. Suggests alternatives on a miss. | | get_icons | Batch-render many icons in one call (great for assembling a UI). | | list_collections | Browse/filter the 214 sets by query, category, or palette. | | get_collection | One set's full metadata: author, license, palette, available styles, category names, samples. | | list_icons | Paginated browse of one set, filtered by substring / style / category. | | find_similar_icons | Style variants of an icon (outline/solid/duotone/…) + same-category siblings — to swap styles consistently. | | suggest_icon_sets | Recommend a few cohesive sets for a use case (query/style/palette) so an agent picks one consistent set instead of mixing. |

Agent-oriented design notes

• Names are prefix:name (e.g. mdi:home) — the same identifier used by @iconify/react, the iconify-icon web component, and UnoCSS (i-mdi-home).
• Styles are detected heuristically from name suffixes and grouped by a shared base, so find_similar_icons and the style filter let an agent keep a consistent look. Canonical styles: outline, solid, duotone, rounded, sharp, thin, light, bold, mono, regular.
• Palette distinguishes monotone (themeable, uses currentColor, accepts a color) from color (brand logos, emoji, flags).
• Ranking is relevance-bucketed (exact → prefix → contains → fuzzy) with a popularity tiebreaker, so search_icons("home") leads with lucide/tabler/mdi rather than obscure sets.

How it works

At build time the full @iconify/json bundle is turned into a self-contained data/icons.db (per-set metadata + the whole IconifyJSON gzipped). At run time the server searches that index with SQLite FTS5 and renders icons via @iconify/utils — no @iconify/json and no network needed at runtime.

The published build is a single bundled dist/server.js (Node ESM); the only runtime dependency is the native better-sqlite3, for which npm fetches a prebuilt binary on install.

Licensing

This server is MIT-licensed. The icons themselves keep their upstream licenses (MIT, Apache-2.0, CC-BY, brand-specific, …) — each icon set's license is available via get_collection and get_icon. Check a set's license before shipping its icons, especially for brand/logo sets.