Better Icons

Better Icons is an MCP server that provides AI agents and developers with direct access to over 200,000 icons from more than 150 icon collections.

You can search for icons using natural language, retrieve optimized SVG code, and sync icons directly to their project files.

Features

• 🔍 150+ Icon Sets: Access more than 200,000 icons spanning 150+ collections, including Lucide, Heroicons, Material Design Icons, Tabler, Phosphor, Remix Icons, and Font Awesome.
• 🧠 Smart Preferences: The server learns from your usage patterns and automatically prioritizes icon collections you use most frequently in future searches.
• 📁 Direct File Integration: Icons are written directly to your project’s icon files in TypeScript, JavaScript, or framework-specific formats instead of being inserted into chat responses.
• ⚡ Batch Operations: Retrieve multiple icons simultaneously with a single command rather than making repeated individual requests.
• 🔄 Cross-Collection Discovery: Find equivalent icons across different collections and visual styles to maintain consistency or explore alternatives.
• 📊 Usage History: Access your recently used icons for quick reuse without searching again.
• 🎨 Framework Flexibility: Export icons as React, Vue, Svelte, Solid components, or raw SVG code depending on your project requirements.

How to Use It

Installation

As an Agent Skill

npx add-skill better-auth/better-icons

As an MCP Server

Run the interactive setup wizard to configure Better Icons for your AI coding environment:

npx better-icons setup

Use the -y flag to skip confirmation prompts and accept defaults automatically. Specify particular agents with -a followed by agent names (cursor, claude-code, opencode, windsurf, vscode). Control configuration scope with -s to choose between global or project-level settings.

CLI Usage

npx better-icons search arrow
npx better-icons get lucide:home > icon.svg

Manual Configuration

Cursor

Edit ~/.cursor/mcp.json to include:

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

Claude Code

Edit ~/.claude/settings.json to include:

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

Available MCP Tools

search_icons

This tool searches across all available icon collections using natural language queries. The agent can request specific results like “Search for arrow icons” or “Search for home icons in the lucide collection.”

Parameters include query (required), which accepts any search term such as “arrow,” “home,” or “user.” The limit parameter (optional) controls result count from 1 to 999, defaulting to 32 results. Use prefix (optional) to filter results by collection name like “mdi” or “lucide.” The category parameter (optional) filters by icon category.

get_icon

This tool retrieves the complete SVG code for a specific icon with customization options. Agents can request icons like “Get the SVG for mdi:home” or “Get lucide:arrow-right with size 24.”

The tool requires icon_id in the format “prefix:name” (for example, “mdi:home”). Optional parameters include color (hex codes like “#ff0000” or “currentColor”), size (pixel dimensions), and format (either “svg” for code or “url” for a direct link).

The response includes raw SVG code, React/JSX component code, Iconify component usage examples, and a direct SVG URL when format is set to “url.”

list_collections

This tool lists all available icon collections with filtering options. Agents can request “List all icon collections” or “Search for material collections.”

Optional parameters include category for filtering by type and search for filtering collections by name.

recommend_icons

This tool provides icon suggestions based on described use cases. Agents can ask “What icon should I use for a settings button?” or “Recommend icons for user authentication.”

The tool requires use_case (a description of what you need). Optional parameters include style (solid, outline, or any) and limit (1 to 20 recommendations).

get_icon_preferences

This tool displays learned preferences showing which icon collections you use most frequently with usage statistics. Agents can request “Show my icon preferences” or “What icon collections do I use most?”

clear_icon_preferences

This tool resets all learned preferences to start fresh. Agents can request “Clear my icon preferences” or “Reset icon preferences.”

find_similar_icons

This tool discovers similar icons or variations across different collections and styles. Agents can ask “Find icons similar to lucide:home” or “What other arrow icons are there like mdi:arrow-right?”

Parameters include icon_id (required) to specify which icon to match, and limit (optional) to control results from 1 to 50, defaulting to 10.

get_icons

This tool retrieves multiple icons simultaneously for improved efficiency. Agents can request “Get these icons: lucide:home, lucide:settings, lucide:user.”

Parameters include icon_ids (required), accepting up to 20 icon identifiers in an array. Optional parameters color and size apply to all retrieved icons uniformly.

get_recent_icons

This tool shows recently used icons for quick reuse. Agents can request “Show my recent icons” or “What icons have I used recently?”

The optional limit parameter controls how many recent icons to display, from 1 to 50, defaulting to 20.

sync_icon

This tool retrieves an icon and automatically adds it to your project’s icon file. This represents the recommended approach for adding icons to a project. Agents can request “Sync the lucide:home icon to my project” or “Add a settings icon to my icons file.”

Required parameters include icons_file (absolute path to your icons file), framework (react, vue, svelte, solid, or svg), and icon_id (prefix:name format). Optional parameters include component_name for custom naming, color, and size in pixels.

The tool responds with confirmation that the icon was added or already exists, the import statement needed to use the icon, and a usage example.

scan_project_icons

This tool scans an icons file to inventory existing icons. Agents can request “What icons are already in my project?” or “Scan my icons file.”

The tool requires icons_file as an absolute path to the target file.

CLI Commands

Searching Icons

Search across all collections using the search command:

better-icons search <query> [options]

The -p or --prefix flag filters results by collection (lucide, mdi, heroicons, etc.). The -l or --limit flag sets maximum results with a default of 32. The --json flag outputs results as JSON for parsing or scripting.

Examples:

better-icons search arrow
better-icons search home --prefix lucide --limit 10
better-icons search settings --json | jq '.icons[:5]'

Retrieving Icons

Get a single icon’s SVG code using the get command:

better-icons get <icon-id> [options]

The icon ID follows the format “prefix:name” such as “lucide:home” or “mdi:arrow-right.” The -c or --color flag sets icon color using hex codes or named colors. The -s or --size flag specifies dimensions in pixels. The --json flag outputs structured data including metadata.

Examples:

npx better-icons get lucide:home > icon.svg
npx better-icons get mdi:account --color '#333' --size 24
npx better-icons get heroicons:check --json

Setup Commands

Configure Better Icons for AI agents using setup commands:

better-icons setup              # Interactive wizard
better-icons setup -y           # Auto-confirm with defaults
better-icons setup -s project   # Project-only configuration
better-icons config             # Display manual instructions

The -y or --yes flag skips confirmation prompts. The -a or --agent flag specifies target agents (cursor, claude-code, opencode, windsurf, vscode). The -s or --scope flag chooses between global (default) or project configuration scope.

FAQs

Q: How does Better Icons save tokens compared to pasting SVG code into chat?
A: The sync_icon tool writes icons directly to your project files and returns only a short confirmation message with import statements. A typical SVG icon contains 200-500 characters of XML markup. Multiplying this across dozens of icons during a development session can consume thousands of tokens. Better Icons replaces this with structured tool calls that reference icons by ID and write them to disk.

Q: What happens when I search for an icon that exists in multiple collections?
A: The search returns results from all matching collections, but the auto-learning system prioritizes collections you have used previously. If you have never used Better Icons before, results appear in a default order based on collection popularity and relevance.

Q: How does the similar icons tool determine similarity?
A: The find_similar_icons tool searches for icons with matching or closely related names across different collections. It identifies the same conceptual icon implemented by different icon libraries. For example, searching for similar icons to “lucide:home” returns home icons from Material Design, Heroicons, Tabler, and other collections so you can compare visual styles while maintaining the same semantic meaning.