What is the Better Icons MCP server?
Better Icons is a TypeScript MCP server and CLI from the better-auth organization. It searches more than 200,000 icons across 150 plus collections, returns SVG or framework code, and can sync an icon into your icons file so the agent does not paste markup into chat.
Better Icons gives an agent a searchable index of icons from over 150 collections, among them Lucide, Heroicons and Material Design. The same package works as an MCP server or as a plain command line tool.
The README names the problem it solves: models often do not know which icons exist, write wrong SVG, mix styles and waste tokens on inline markup. The server returns real icons by id instead.
What changes in your agent's output
- Icon ids use a
prefix:nameform such aslucide:home, so the agent picks from icons that exist. - The sync tool writes the icon into a
.tsx,.tsor.jsicons file for React, Vue, Svelte, Solid or raw SVG. - It remembers which collections you use and ranks them first in later searches.
- A scan tool reads your icons file so the agent can see what is already there.
Install paths
Run the setup command and it configures the server for the agents listed in the README. The README also offers an agent skill for the CLI features, or you can install the CLI globally with npm or Bun.
Who Better Icons is for
Best for
- Front-end developers who want consistent icons added to a component project without hunting through icon sites.
- Teams that already settled on one library, such as Lucide, and want the agent to stay inside it.
- Builders who want to compare it with Unicon MCP, another icon search server.
Not for
- Custom brand illustration. It retrieves existing icons and does not draw new ones.
- Page builders that take icons from their own picker. Keyline Icons MCP offers another route, and Font MCP covers type instead.
- Anyone needing a hosted service. The README setup runs a local npx process, with no remote endpoint listed.
Use it with UiChemy
Better Icons helps a developer pick consistent icons in code. For WordPress pages, UiChemy converts a Figma design into editable layouts, and Composer writes HTML, CSS and JS for them. Click Get Started on uichemy.com.
Connect Better Icons MCP Server: Search 200,000 Icons From Your Agent to your AI client
npx better-icons setupRun the setup wizard
Execute
npx better-icons setup. It walks through Cursor, Claude Code, OpenCode, Windsurf, VS Code with Copilot and Google Antigravity. Add-yto skip prompts.Choose a scope
Setup defaults to global. Pass
-s projectto configure only the current project, or-awith agent names to limit the list.Or edit the config
Paste the JSON entry above into your client's MCP file, for example
~/.cursor/mcp.json, then restart the client.Optional: add the skill
The README offers a skill that enables the CLI features in your agent environment. Install it from the repository instructions.
Test from the terminal
Run
npx better-icons search arrow --limit 10, thennpx better-icons get lucide:hometo confirm results come back.
Client configuration
{
"mcpServers": {
"better-icons": {
"command": "npx",
"args": ["-y", "better-icons"]
}
}
}Endpoints and ports
npx -y better-iconsstdio, no API key listedbetter-icons search <query>Options for prefix, limit and JSON outputhttps://github.com/better-auth/better-iconsMIT licenseWhat you can do with it
- Very wide catalogThe README cites more than 200,000 icons from over 150 collections.
- Writes to your projectSync adds the icon to your icons file instead of printing SVG into the chat.
- Batch retrievalGet up to 20 icons in one call, which is lighter than repeated single lookups.
- Cross-collection matchesFind similar icons across styles when one set lacks the glyph you need.
- Learns your setsCollections you use get priority in later searches.
- Five code targetsReact, Vue, Svelte, Solid and raw SVG are supported by the sync tool.
- Color and size optionsRetrieval accepts a color value such as
currentColorand a pixel size. - CLI includedSearch and fetch icons from a terminal, with JSON output for scripts.
Tools it exposes
search_icons
Searches all collections by query, with optional prefix, category and limit.
get_icon
Returns SVG, React or Iconify code, or a URL, for one icon id.
get_icons
Fetches up to 20 icons in one call.
list_collections
Lists the available icon collections, with optional search.
recommend_icons
Suggests icons for a described use case and a solid or outline style.
find_similar_icons
Finds the same or similar icon across other collections.
sync_icon
Adds an icon to your project's icons file for a chosen framework.
scan_project_icons
Reads an icons file to show which icons it already has.
get_recent_icons
Shows icons you used recently.
get_icon_preferences
Shows the learned collection preferences.
clear_icon_preferences
Resets the learned preferences.
Frequently asked questions
What is Better Icons MCP?
It is an MCP server and CLI from the better-auth organization. An AI agent uses it to search more than 200,000 icons across 150 plus collections, fetch SVG or component code, and add icons to a project file.
How do I install Better Icons?
Run npx better-icons setup and choose your agents, or add the entry npx -y better-icons to your client's MCP config by hand. You can also install the CLI globally with npm or Bun for terminal use.
Which agents does the setup wizard support?
The README lists Cursor, Claude Code, OpenCode, Windsurf, VS Code with Copilot and Google Antigravity. Any other MCP client can use the same npx command added manually to its config.
Does it need an API key?
The README shows no API key, account or environment variable anywhere in its setup. The config entry is only the npx command, so you can start without credentials, and the CLI works the same way.
Which frameworks can it write icons for?
The sync tool takes React, Vue, Svelte, Solid or plain SVG as the framework. It writes into the icons file path you provide and returns the import statement and a usage example.
Can it recommend an icon for a button?
Yes. The recommend tool takes a described use case such as a settings button, an optional solid or outline style and a limit, then returns suggestions drawn from the collections it indexes.
Is Better Icons free to use?
The repository is MIT licensed. Individual icon collections are separate projects with their own terms, so check the license of the collection you pick before shipping it on a commercial site.


