Skip to main content
Glama

@sohampatwardhan/iconify-mcp

npm version

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.

Contact sheet of twelve Lucide icons rendered by iconify-mcp

Tools

Tool

What you get

list_collections

Filter the catalog by name, prefix, or category. Each hit includes author, license, icon count, and sample ids.

get_collection

One collection: license, categories, a page of icon names, and a PNG of its sample icons.

search_icons

Keyword search (query, optional prefix / prefixes / category, limit, start). Results include Iconify ids, licenses, and Icônes links, plus a contact-sheet PNG.

get_icon

One icon (prefix:name): SVG, dimensions, collection, license, alias parent, Icônes URL, and a PNG. Snippets cover SVG, data URL, Vue, React, Svelte, UnoCSS, Tailwind, and the Iconify name.

preview_icons

One labeled contact sheet for a list of ids, or for the top search matches. size, color, background, and columns are configurable.

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:house

  • SVG and a data URL

  • Iconify SVG URL: https://api.iconify.design/lucide/house.svg

  • Vue, 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

iconify://collections

Collection list with licenses

iconify://collection/{prefix}

One collection, including up to 200 icon names

iconify://icon/{prefix}/{name}.svg

SVG

iconify://icon/{prefix}/{name}.png

128px PNG on white

iconify://icon/{prefix}/{name}.json

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@latest

The 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.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after saving.

Claude Code

claude mcp add iconify -- npx -y @sohampatwardhan/iconify-mcp@latest

VS 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 3333

The 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.js

A 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.js

Examples

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 /collections and GET /collection

  • GET /search

  • GET /{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

ICONIFY_API_URL

https://api.iconify.design

API origin

ICONES_MIN_INTERVAL_MS

100

Minimum gap between API calls

ICONES_CACHE

enabled

Set to 0 to disable the memory cache

Development

npm install
npm run lint
npm test
npm run typecheck
npm run build
node dist/cli.js --help
npm run smoke

npm 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-tags

Run 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 tools
get_collectionGet an icon collectionA
Read-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 iconA
Read-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 collectionsA
Read-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 iconsA
Read-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 iconsA
Read-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

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provide 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.
      4
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      405 npm
      21
      GPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      4
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching, fetching SVG, and discovering icons from Iconify's 200,000+ icon library across 150+ sets.
      42 npm
      MIT