TrueIcon

TrueIcon is an MCP server that gives AI coding assistants exact, version-correct icon references. Your assistant searches the icon packages your project actually uses (lucide-react, react-icons, @heroicons/react, @phosphor-icons/react, @tabler/icons-react, iconoir-react, @fluentui/react-icons, @carbon/icons-react, @ant-design/icons, @mui/icons-material, @radix-ui/react-icons, @remixicon/react and the Font Awesome Free packages) and gets back real icon names, import paths and a ready-to-paste import line.

Why

AI assistants often guess icon names. The guess can be an icon that never existed, one renamed a few releases ago, or one from a different library, and you only find out when the build fails. TrueIcon closes that gap:

• It reads which icon packages and versions your project uses.
• It downloads those exact versions from npm and indexes every icon once.
• The assistant calls search_icons and gets results that are guaranteed to exist in that version, for example import { Trash2 } from 'lucide-react';.

Supported providers

Tools accept either the provider id or the npm package name ("lucide" or "lucide-react"). Usage snippets are for React. Phosphor weights all share one component, so pass the record's style as the weight prop (e.g. <TrashIcon weight="bold" />); the usage snippet only shows the import. Font Awesome imports are icon definitions, not components: render them with @fortawesome/react-fontawesome, e.g. <FontAwesomeIcon icon={faTrashCan} />.

Install

TrueIcon needs Node.js 20 or newer.

# Run without installing (this is what the MCP configs below do)
npx -y trueicon

# Or install globally and run the `trueicon` binary
npm i -g trueicon
trueicon

trueicon is a stdio MCP server. Your MCP client starts it; running it by hand only prints trueicon: v<version> running on stdio to stderr and waits for JSON-RPC on stdin.

Quick start

1. Register TrueIcon with your MCP client (Claude Code, Claude Desktop, or VS Code and Cursor).
2. Ask your assistant for an icon.

That's it for most projects. TrueIcon finds the icon packages your package.json lists and the versions installed in node_modules. The first search for each package downloads and indexes it, which takes a few seconds. Later searches use the local cache.

Configuration

Which icon packages are searched

• By default, every supported package listed in dependencies or devDependencies of your package.json.
• With .iconmcp.json in the project, exactly the packages it lists. Use it to search only some of your icon packages, to add one your package.json doesn't list (for example one that comes in through a UI kit), or to pin a version.

{
  "providers": [
    { "package": "lucide-react" },
    { "package": "react-icons", "version": "5.3.0" },
    { "package": "@heroicons/react", "version": "^2.1.0" }
  ]
}

• Unsupported packages in .iconmcp.json are skipped, and search_icons reports them as a warning.
• Invalid JSON or a malformed entry makes the tools return an error that names the file and the bad field.
• If neither file names a supported package, search_icons returns an error that says which directory it looked in. You can still pass provider to a tool call.

Semantic search (opt-in)

Set "semantic": true in .iconmcp.json to add meaning-based ranking to search_icons. Each query is embedded with a small local model (all-MiniLM-L6-v2, ~90MB downloaded once to the transformers.js cache) and matched against per-icon vectors built at index time; those semantic candidates are merged with the keyword results using reciprocal rank fusion, so exact-name matches still win while conceptual queries like "remove background" can surface eraser.

{
  "providers": [{ "package": "lucide-react" }],
  "semantic": true
}

Semantic search runs on @huggingface/transformers, which is an optional peer dependency and is not installed by default, so installs that never enable the flag stay lean. To enable semantic search, install it once (about 400MB) alongside trueicon:

npm install @huggingface/transformers

If the flag is on but the package is missing, search_icons and get_icon fall back to keyword-only indexes and return a one-line warning with the install command.

Toggling the flag rebuilds the indexes once (vectors are stored in index.json alongside each record, and meta.json records the embedding model). It stays fully local: no data leaves your machine. TRUEICON_SEMANTIC=1 (or 0) overrides the flag for one-off runs.