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) 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';.

Related MCP server: Svg/icons MCP

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.

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: v0.2.0 running on stdio to stderr and waits for JSON-RPC on stdin.

Quick start

1. Add a .iconmcp.json to your project root that lists your icon packages:

   {
     "providers": [
       { "package": "lucide-react" },
       { "package": "@heroicons/react", "version": "2.1.5" }
     ]
   }

2. Register TrueIcon with your MCP client (Claude Code or Claude Desktop).

3. Ask your assistant for an icon. The first search for each package downloads and indexes it, which takes a few seconds. Later searches use the local cache.

Configuration: .iconmcp.json

TrueIcon looks for .iconmcp.json in the project directory. That is $TRUEICON_PROJECT_DIR if set, otherwise the server's working directory.

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

• If the file is missing, no providers are configured. search_icons then only works when you pass provider explicitly, and get_icon still works.

• Unsupported packages in the list 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.

Environment variables

Versions

Auto-detection

A provider's version is resolved in this order:

1. The version argument passed to the tool call, if any.

2. The provider's version in .iconmcp.json.

3. The version range declared for the package in the project's package.json, checking dependencies first and then devDependencies.

If none of these is available, the tool asks you to pin the version or add the package to package.json. TrueIcon reads the declared range from package.json. It does not read node_modules or the lockfile. For a range, it indexes the range's base version: ^0.460.0 indexes lucide-react@0.460.0. For a || b ranges, only the first part counts. To match an exact installed version, pin it in .iconmcp.json.

Version policy

Indexes are keyed by major.minor:

• Patch versions are ignored. One index serves all of 0.460.x. The index built from 0.460.0 answers requests for 0.460.3.

• A minor change gets its own index. Bumping lucide-react from 0.460 to 0.461 builds a fresh index on the next search, with no manual step.

• Majors are strict. A different major is always a separate index and is never served from another major's index.

• Cached indexes rebuild automatically when the bundled synonyms.json changes (detected by hash) or the index format changes.

Using it with Claude

Claude Code

Add TrueIcon from your project directory:

claude mcp add trueicon -- npx -y trueicon

Or commit a .mcp.json at the project root to share it with your team:

{
  "mcpServers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"]
    }
  }
}

Claude Code starts the server in your project directory, so it finds .iconmcp.json and package.json there. If it runs from somewhere else, add "env": { "TRUEICON_PROJECT_DIR": "/absolute/path/to/project" }.

Claude Desktop

Claude Desktop doesn't start servers in your project directory, so set TRUEICON_PROJECT_DIR. Edit claude_desktop_config.json: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"],
      "env": {
        "TRUEICON_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Restart Claude Desktop after editing the file.

Using it in VS Code and Cursor

Use the install badges at the top of this README. They add TrueIcon with TRUEICON_PROJECT_DIR set to ${workspaceFolder}, so it searches the project you have open.

To add it by hand in VS Code, create .vscode/mcp.json in your project:

{
  "servers": {
    "trueicon": {
      "command": "npx",
      "args": ["-y", "trueicon"],
      "env": {
        "TRUEICON_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

In Cursor, use the same entry under "mcpServers" in .cursor/mcp.json.

Tools

Every tool returns a single JSON text block. On failure, the block is {"error": "..."} and the MCP result is flagged with isError: true.

search_icons

Searches the index and returns ranked matches with import statements.

Example call:

{ "query": "trash", "provider": "lucide", "limit": 3 }

Response:

{
  "results": [
    { "name": "trash", "importName": "Trash", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Trash } from 'lucide-react';", "score": 2.0e-14 },
    { "name": "trash-2", "importName": "Trash2", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Trash2 } from 'lucide-react';", "score": 1.6e-6 },
    { "name": "delete", "importName": "Delete", "importPath": "lucide-react", "package": "lucide-react",
      "version": "0.460.0", "style": "outline", "set": "lucide",
      "usage": "import { Delete } from 'lucide-react';", "score": 1.2e-4 }
  ]
}

How search works:

• provider, style and set are exact, case-insensitive filters. They are applied before ranking.

• Ranking uses Fuse.js fuzzy matching over the icon name, import name, keywords and tags. Small typos are tolerated: "detele" finds Delete.

• score runs from 0 (perfect) to 1, so lower is better. Results from several providers are merged and sorted by score.

• Multi-word queries are tokenized: each word is matched on its own, only icons that match every word are kept, and they are ranked by their average score. So "trash can" finds trash-can icons. Short keyword queries ("trash", "settings", "beer") still cast the widest net.

• If one provider fails, for example because its version can't be resolved or the download fails, its results are skipped and a warnings array explains why. The other providers still return results.

list_providers

Takes no arguments. Returns the providers configured in .iconmcp.json with their resolved versions, plus every provider TrueIcon supports.

{
  "configured": [
    { "id": "lucide", "package": "lucide-react", "version": "^0.460.0", "source": "package.json" },
    { "id": "heroicons", "package": "@heroicons/react", "version": "2.1.5", "source": "iconmcp.json" }
  ],
  "registry": [
    { "id": "react-icons", "package": "react-icons", "description": "Aggregated icon sets (Font Awesome, Material, Feather, and more) as React components" },
    { "id": "lucide", "package": "lucide-react", "description": "Lucide icons as React components" },
    { "id": "heroicons", "package": "@heroicons/react", "description": "Heroicons by the Tailwind CSS team as React components" },
    { "id": "phosphor", "package": "@phosphor-icons/react", "description": "Phosphor icons in six weights (thin, light, regular, bold, fill, duotone) as React components" },
    { "id": "tabler", "package": "@tabler/icons-react", "description": "Tabler icons (outline and filled) as React components" },
    { "id": "iconoir", "package": "iconoir-react", "description": "Iconoir icons (regular and solid) as React components" },
    { "id": "fluentui", "package": "@fluentui/react-icons", "description": "Microsoft Fluent UI System icons (regular, filled and color) as React components" },
    { "id": "carbon", "package": "@carbon/icons-react", "description": "IBM Carbon Design System icons as React components" },
    { "id": "antdesign", "package": "@ant-design/icons", "description": "Ant Design icons (outlined, filled and two-tone) as React components" }
  ]
}

source is "iconmcp.json" or "package.json". version and source are null when neither file provides a version. id is null for a configured package TrueIcon doesn't support.

get_icon

Gets the full record and import statement for an icon whose name the assistant already knows.

Example call:

{ "name": "Trash2", "provider": "lucide" }

Response:

{
  "id": "lucide-react@0.460:trash-2",
  "name": "trash-2",
  "importName": "Trash2",
  "importPath": "lucide-react",
  "provider": "lucide",
  "package": "lucide-react",
  "version": "0.460.0",
  "style": "outline",
  "set": "lucide",
  "categories": [],
  "tags": [],
  "keywords": ["trash", "2", "delete", "remove", "bin", "garbage", "rubbish"],
  "svg": "<path d=\"M3 6h18\"/><path d=\"M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6\"/>…",
  "usage": "import { Trash2 } from 'lucide-react';"
}

svg is the icon's inner SVG markup, meaning the children of the root <svg> element. Heroicons uses the same import name in every size and style (TrashIcon). Pass the full variant name, such as "trash-24-outline", to get a specific one.

ping

A health check that returns {"status":"ok","server":"trueicon"}.

Indexing and caching

The first time a tool needs package@major.minor, TrueIcon does the following:

1. It downloads the package tarball from https://registry.npmjs.org, verifies its sha512 integrity, and extracts it into the cache.

2. It parses the package's shipped files with the provider's adapter. Nothing is executed. Icons are read from the compiled source.

3. It writes index.json (one record per icon) and meta.json (exact version, synonyms hash, index format, build time).

Later calls only read index.json. Package files are never touched at query time, and your node_modules is never read or modified. If several tool calls need the same index at once, they share one download.

The cache root is ~/.trueicon/cache, or $TRUEICON_CACHE if set:

~/.trueicon/cache/
├── lucide-react@0.460/          # extracted package + index.json + meta.json
├── react-icons@5.3/             # extracted package + index.json + meta.json
├── heroicons-react@2.1/         # extracted @heroicons/react package
└── @heroicons/react@2.1/        # index.json + meta.json for @heroicons/react

• Downloads go to <package>@<major.minor>, where scoped names are flattened: @heroicons/react becomes heroicons-react. A .download-complete marker is written last, and a directory without it is treated as partial and replaced.

• Indexes go to <package>@<major.minor>/index.json and meta.json. For unscoped packages this is the same directory as the download.

• The cache is safe to delete. It is rebuilt on demand, which needs network access.

Each record's keywords combine the name parts, the tags, and synonym expansions from the bundled synonyms.json. The expansions are added at index time, so "bin" finds Trash2 without any extra work at query time.

Contributing

git clone https://github.com/manikumarkv/trueicon.git
cd trueicon
npm ci
npm run build      # compile to dist/
npm test           # vitest
npm run lint       # eslint
npm run typecheck  # tsc --noEmit

CI runs lint, typecheck and tests on Node 20 and 22 for every push and pull request.

Tests

The fixtures only change when someone edits them, so they can't catch a provider that changes its package format upstream. npm run smoke does. Run npm run smoke -- lucide tabler to check only some providers. CI runs it on pull requests that change src/providers/, src/indexer/ or src/cache/, and every Monday against the latest releases.

Testing and debugging locally

These scripts build the server and run it against playground/, a sample project that lists all 9 providers at their latest versions. They use a separate cache in .cache/dev/, so your real ~/.trueicon cache is untouched.

# Call one tool and print the result
npm run dev:call -- list_providers
npm run dev:call -- search_icons query="trash can" limit=5
npm run dev:call -- search_icons query=trash provider=lucide version=1.47.0
npm run dev:call -- get_icon name=Trash2 provider=lucide

# Open the MCP Inspector web UI on the local build
npm run dev:inspect

# Same, with the Node debugger on port 9229
npm run dev:debug

• Arguments are key=value pairs. Numbers and booleans are parsed, so limit=5 is sent as a number.

• Another project: set TRUEICON_PROJECT_DIR to test against its package.json and .iconmcp.json, e.g. TRUEICON_PROJECT_DIR=~/code/my-app npm run dev:inspect.

• Rebuild indexes: add --fresh to delete the dev cache first, e.g. npm run dev:call -- --fresh search_icons query=trash. Use it after changing an adapter.

• Breakpoints: run npm run dev:debug, then in VS Code use Debug: Attach to Node Process, or open chrome://inspect in Chrome. Source maps are on, so breakpoints work in the .ts files under src/. Set them, then call a tool from the Inspector.

• Logging: stdout carries the MCP protocol, so log with console.error. It shows in the terminal for dev:call and in the Inspector's server log for dev:inspect.

Extending synonyms.json

src/synonyms/synonyms.json maps a term to extra search terms:

{
  "trash": ["delete", "remove", "bin", "garbage", "rubbish"],
  "logout": ["sign-out", "signout", "exit", "leave"]
}

• Keys are matched against an icon's name parts (the name split on -) and its tags. trash-2 matches the key trash.

• Values are added to that icon's keywords.

• Expansion is one-way. If bin should also find icons named delete, add both "trash": ["bin"] and "delete": ["bin"], or add a reverse entry.

• Write keys and values in lowercase, and give every key a non-empty array of strings. tests/synonyms.test.ts checks this.

• Changing the file changes its hash, so cached indexes rebuild automatically on the next search.

Adding a provider

1. Register it in src/providers/registry.ts with a stable id, the npm package and a short description.

2. Write an adapter in src/providers/adapters/<provider>.ts that exports parseIcons(packageDir: string): RawIcon[] (see src/providers/adapter.ts). It gets the extracted package directory and returns one RawIcon per icon:

   • name: kebab-case and unique within the package, because it becomes part of the record id. Use toKebabCase from adapter.ts. If the package has variants with clashing component names, add the variant to the name, as the heroicons, react-icons, phosphor and iconoir adapters do.

   • importName and importPath: the exact export and module specifier a user would import.

   • svg: the inner SVG markup. LiteralCursor (src/providers/jsLiteral.ts) parses JS object and array literals without executing code. toSvgAttrs and renderSvg (src/providers/svg.ts) turn React props into SVG markup, and parseCreateElement reads compiled createElement(...) trees.

   • Optional style, set, categories and tags.

   • Put a comment at the top of the adapter describing the package's file layout, as the existing adapters do.

3. Wire it up in src/providers/adapters/index.ts by adding it to ADAPTERS under the provider id.

4. Test it. Add a small pinned fixture under tests/fixtures/<provider>/ that mirrors the package layout, with a few real icon files plus any files the adapter must skip. Then add tests/adapters/<provider>.test.ts, covering name mapping, import paths, SVG output and buildIndex record ids like the existing adapter tests. tests/adapters/common.test.ts fails if a registered provider has no adapter.

5. Add it to the tool tests by adding a case to CASES in tests/providers-tools.test.ts: the fixture, a search query, one icon with its exact import line, and a deprecated alias if the package has them. The test fails if a registered provider has no case.

6. Add smoke targets to TARGETS in scripts/smoke.mjs: a few well-known import names and a minimum icon count well below the real one. Then run npm run smoke -- <provider> to check it against the real published package.

License

MIT © 2026 manikumarkv