iconify-mcp
Summary: iconify-mcp lets a model search the public Iconify catalog (the one behind Icônes) and actually see icons as rendered PNG contact sheets, alongside metadata, licenses, and copy-paste snippets.
Browse collections (
list_collections): filter the Iconify catalog by query, prefix, or category; each hit returns author, license, icon count, and sample ids.Inspect one collection (
get_collection): license, author, category counts, a page of icon names (with offset/category paging), plus a PNG of its sample icons by default.Search icons (
search_icons): keyword search over icon names and keywords with optionalprefix/prefixes/category,limit, andstart; returns ids, licenses, Icônes links, and a labeled contact-sheet PNG.Fetch a single icon (
get_icon): SVG, dimensions, collection, license, alias parent, Icônes URL, and a PNG, with snippets for SVG, data URL, Iconify URL, Vue, React, Svelte, UnoCSS, Tailwind, and the plain Iconify name.Compare icons visually (
preview_icons): build one labeled contact sheet for a hand-picked list of ids or for top search matches, with configurable size, color, background, and columns (up to 24 icons).Read resources over
iconify://(alsoicones://): collection lists, a single collection (up to 200 icon names), and per-icon.svg, 128px.png, and.json(metadata + snippets).Know the licensing: every tool and resource surfaces the collection's license title, SPDX id, and URL, and SVG snippets embed a license comment.
Run it flexibly: stdio by default (npx, Cursor, Claude Desktop, Claude Code, VS Code) or stateless localhost Streamable HTTP at
/mcpwithGET /health.Tune API usage: point
ICONIFY_API_URLat your own Iconify API, adjustICONES_MIN_INTERVAL_MS, or disable the in-memory cache withICONES_CACHE=0.
Integrates with the public Iconify icon catalog to list and inspect collections with license details, search icons by name or keyword, fetch individual icons as SVG/PNG with metadata and framework snippets, and generate labeled contact-sheet previews.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@iconify-mcp search for arrow icons in lucide and show me the contact sheet"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@sohampatwardhan/iconify-mcp
Unofficial community MCP server for Iconify. It searches the public Iconify catalog, returns each collection's license, and sends PNG previews back as MCP image content so a model can see the icons.
Icon pages link to Icônes, Anthony Fu's icon browser, which is a front end over the same catalog.
![]()
Tools
Tool | What you get |
| Filter the catalog by name, prefix, or category. Each hit includes author, license, icon count, and sample ids. |
| One collection: license, categories, a page of icon names, and a PNG of its sample icons. |
| Keyword search ( |
| One icon ( |
| One labeled contact sheet for a list of ids, or for the top search matches. |
search_icons and get_collection include a preview image by default. Pass preview: false when you only want the JSON.
Iconify search matches names and keywords. It does not search by visual similarity. Use the contact sheet to compare candidates.
Code snippets
get_icon returns the formats Icônes offers:
Iconify name:
lucide:houseSVG and a data URL
Iconify SVG URL:
https://api.iconify.design/lucide/house.svgVue, React, and Svelte components
UnoCSS:
<div class="i-lucide-house"></div>Tailwind (Iconify plugin):
<span class="icon-[lucide--house]"></span>
Snippet SVGs keep currentColor so they inherit text color. Pass color (for example #b45309) when the SVG and the PNG should use a fixed color. PNGs default to #1c1917 on white. Palette icons that do not use currentColor keep their original colors.
Resources
URI | Body |
| Collection list with licenses |
| One collection, including up to 200 icon names |
| SVG |
| 128px PNG on white |
| Metadata and snippets |
iconify:// is the scheme to use. The same resources are also registered on icones:// so older URIs keep working.
Icônes links look like https://icones.js.org/collection/lucide?icon=lucide:house.
Related MCP server: Iconify MCP Server
Setup
Requires Node.js 20 or newer.
npx -y @sohampatwardhan/iconify-mcp@latestThe published bin is iconify-mcp. icones-mcp is a compatibility alias for the same program. Stdio is the default. Logs go to stderr so they stay off the JSON-RPC stream. The MCP server name is iconify-mcp.
Cursor
Add this to ~/.cursor/mcp.json or the project's .cursor/mcp.json:
{
"mcpServers": {
"iconify": {
"command": "npx",
"args": ["-y", "@sohampatwardhan/iconify-mcp@latest"]
}
}
}Claude Desktop
The same mcpServers block goes in the desktop config:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Restart Claude Desktop after saving.
Claude Code
claude mcp add iconify -- npx -y @sohampatwardhan/iconify-mcp@latestVS Code
Create .vscode/mcp.json:
{
"servers": {
"iconify": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sohampatwardhan/iconify-mcp@latest"]
}
}
}Streamable HTTP
HTTP mode is stateless and has no authentication. Bind it to localhost.
npx -y @sohampatwardhan/iconify-mcp@latest --http --port 3333The MCP endpoint is http://127.0.0.1:3333/mcp. A client config looks like:
{
"mcpServers": {
"iconify": {
"url": "http://127.0.0.1:3333/mcp"
}
}
}GET /health returns ok.
MCP Inspector
The web UI:
npm install
npm run build
npx @modelcontextprotocol/inspector node dist/cli.jsA non-interactive check of the stdio server:
npx @modelcontextprotocol/inspector --cli --method tools/list node dist/cli.js
npx @modelcontextprotocol/inspector --cli --method tools/call \
--tool-name get_icon \
--tool-args-json '{"icon":"lucide:house","size":64}' \
node dist/cli.jsExamples
Search and look at the sheet:
{
"name": "search_icons",
"arguments": { "query": "arrow", "prefix": "lucide", "limit": 8 }
}Fetch one icon as a React component and a 128px PNG:
{
"name": "get_icon",
"arguments": { "icon": "lucide:house", "formats": ["react", "svg", "iconify"] }
}Compare a hand-picked set. This is the call that produced the image at the top of the README:
{
"name": "preview_icons",
"arguments": {
"title": "Lucide",
"columns": 4,
"size": 72,
"icons": [
"lucide:house", "lucide:search", "lucide:heart", "lucide:star",
"lucide:sun", "lucide:moon", "lucide:cloud", "lucide:camera",
"lucide:bell", "lucide:settings", "lucide:user", "lucide:mail"
]
}
}Prompts that work well once the server is connected:
"Search Lucide for a house icon and show me the candidates."
"Get the SVG and a Svelte component for
tabler:brand-github.""Make a contact sheet of weather icons from Phosphor."
Licenses
This server is MIT. See LICENSE.
Icon artwork is not relicensed. Every collection on Iconify has its own license (MIT, Apache-2.0, ISC, CC BY 4.0, and others). list_collections, get_collection, search_icons, get_icon, and preview_icons return that license's title, SPDX id, and URL. SVG snippets include a comment with the collection, author, and license. Read that license before shipping an icon.
Contact-sheet labels are set in Inter, which is bundled under the SIL Open Font License. The license text is in assets/fonts/OFL.txt. Rasterized labels in a PNG are pixels. The font file itself stays under the OFL.
Data source
This server calls the public Iconify API at https://api.iconify.design. Icônes (icones.js.org) is the browsing UI those icon links open. The client uses:
GET /collectionsandGET /collectionGET /searchGET /{prefix}.json?icons=...
SVGs are built locally with @iconify/utils and rasterized with @resvg/resvg-js. The client keeps at least 100ms between requests, caches collection metadata, search results, and icon bodies in memory, and retries 429 and 5xx responses.
The public API is a shared service. Point ICONIFY_API_URL at your own Iconify API instance if you need higher volume.
Variable | Default | Purpose |
|
| API origin |
|
| Minimum gap between API calls |
| enabled | Set to |
Development
npm install
npm run lint
npm test
npm run typecheck
npm run build
node dist/cli.js --help
npm run smokenpm run lint checks TSDoc comments with eslint-plugin-tsdoc (tsdoc/syntax). npm test includes rendering tests and a live call against the public API. npm run smoke starts the built stdio server, calls preview_icons, and writes docs/contact-sheet.png unless CONTACT_SHEET_OUT is set. It also copies the PNG to contact-sheet.png inside SMOKE_OUT, or the system temp directory when SMOKE_OUT is unset. CI runs npm ci, then lint, typecheck, test, build, and smoke.
prepublishOnly compiles TypeScript into dist/ before the package is packed.
Releasing
@sohampatwardhan/iconify-mcp is published only by .github/workflows/release.yml, using GitHub OIDC trusted publishing. 0.2.1 was published that way. Do not run npm publish from a laptop or an agent session, and do not create an npm token.
Bump the version on main after the release commit is there. npm version updates package.json and package-lock.json and creates the matching tag. src/version.ts reads the version from package.json, so leave that file's version line alone.
npm version patch # or minor, or major
git push --follow-tagsRun those commands from main. A tag pushed from a feature branch does not release. Do not move a tag or publish the same version again.
The workflow rejects a tag that is not v plus the package.json version, then runs npm ci, lint, typecheck, test, build, and smoke, publishes with npm publish --provenance --access public, and opens a GitHub Release with generated notes.
Available Tools
5 toolsget_collectionGet an icon collectionARead-onlyIdempotent
Get one Iconify collection: license, author, category counts, and a page of icon names. By default also returns a PNG contact sheet of the collection's sample icons so you can see the style. Set preview to false to skip the image. Pass category to page icons inside one category.
Inputs: prefix (required), limit, offset, preview, +1 more.
get_iconGet an iconARead-onlyIdempotent
Get one icon by Iconify id (prefix:name). Returns dimensions, collection, license, alias parent when this name is an alias, the Icônes URL, code snippets, and a PNG you can see. Snippets cover raw SVG, a data URL, Vue, React, Svelte, an UnoCSS class, a Tailwind Iconify class, and the Iconify name. Snippet SVGs stay on currentColor unless color is set. Use preview_icons to compare several icons.
Inputs: icon (required), size, color, aliases, +3 more.
list_collectionsList icon collectionsARead-onlyIdempotent
List Iconify collections available on Icônes, including license, author, icon count, category, and sample icon ids. Filter with query, prefix, or category. Does not return icon images; call get_collection or preview_icons to see icons. Icon sets keep their own licenses.
Inputs: limit, query, prefix, category.
preview_iconsPreview iconsARead-onlyIdempotent
Render a labeled PNG contact sheet of several icons so you can compare them in one image. Pass Iconify ids, or a search query plus an optional prefix, and the top matches are drawn. Supports size, color, background, and columns. Each icon's license is included in the text result. At most 24 icons.
Inputs: size, color, icons, limit, +6 more.
search_iconsSearch iconsARead-onlyIdempotent
Search icons across Iconify, the catalog behind Icônes (https://icones.js.org). Matches icon names and keywords, not arbitrary visual similarity. Returns icon ids, the collection license, and an Icônes URL. By default also returns one labeled PNG contact sheet of the matches so you can see and compare them. Set preview to false for text only.
Inputs: query (required), size, color, limit, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct resource/action focus: list_collections (catalog browsing), get_collection (one set's metadata + icon page), search_icons (cross-collection discovery), get_icon (single icon details/snippets), preview_icons (visual comparison). The only friction is that search_icons and get_collection both emit PNG contact sheets by default, blurring the line with preview_icons, but the descriptions explicitly steer callers to preview_icons for comparison.
All five names follow a clean snake_case verb_noun pattern (list_collections, get_collection, search_icons, get_icon, preview_icons). Verbs are used consistently and predictably: list/search for discovery, get for single-item retrieval, preview for rendering.
Five tools is well-scoped for an icon catalog browser: one discovery-listing tool, one collection lookup, one search, one item lookup, and one batch preview. Nothing extraneous and no obvious repetition of capability.
The surface covers the full browse lifecycle (list → detail → search → single icon with snippets → visual compare) with no dead ends for typical use. Minor gaps: no tool to fetch/export a raw Iconify collection JSON or bulk icon data, and exhaustive icon enumeration relies on implicit paging inside get_collection.
Maintenance
Related MCP Connectors
Unofficial Iconify MCP — wraps the Iconify public API (free, no auth)
Icons for agentic development: search & fetch 366,000+ open-source icons as SVG/PNG. No API key.
Search open SVG icon packs and fetch exact SVG markup from coding agents through MCP.
Search character packs and icon sets as SVG: scenes, licences and credit lines. Read only.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvide access to Iconify's MCP server with over 200,000 open-source vector ICONS, supporting icon set browsing, searching, and obtaining multi-framework usage examples.42Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides access to over 200,000 open-source vector icons from more than 200 icon sets via the Iconify API. It enables users to browse, search, and retrieve specific icon data along with usage examples for popular web frameworks like React, Vue, and Tailwind CSS.490 npm24GPL 3.0
- AlicenseAqualityDmaintenanceProvides access to Iconify's 200,000+ open source vector icons from 200+ icon sets, enabling search, browsing, and retrieval of icon data with framework usage examples.4MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching, fetching SVG, and discovering icons from Iconify's 200,000+ icon library across 150+ sets.MIT