TrueIcon

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, the Font Awesome Free packages, and the Vue and Svelte packages of Lucide, Heroicons, Tabler and Phosphor) 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

Vue and Svelte

These index the same artwork as the React packages above, with each package's own component names and import paths.

Heroicons has no official Svelte package. Angular packages aren't supported yet.

Tools accept either the provider id or the npm package name ("lucide" or "lucide-react"). Usage snippets are import lines, which work the same way in React, Vue and Svelte. Phosphor weights all share one component, so pass the record's style as the weight prop (e.g. ); the usage snippet only shows the import. Font Awesome imports are icon definitions, not components: render them with @fortawesome/react-fontawesome, e.g. .

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

Which directory is the project

TrueIcon reads package.json, .iconmcp.json and node_modules from the project directory. It picks the first of:

1. $TRUEICON_PROJECT_DIR, when set.
2. A folder your MCP client shares with the server (MCP roots) that contains a package.json or .iconmcp.json. Clients that support roots, like VS Code, tell TrueIcon which folders you're working in, so it follows your o