Better Icons

The MCP server for searching and retrieving 200,000 icons from 150+ icon sets.

Get Started

npx better-icons setup

This will interactively configure the MCP server for:

• Cursor
• Claude Code
• OpenCode
• Windsurf
• VS Code (Copilot)

Or configure manually.

Why?

Icons are a common pain point in AI-assisted coding. Models often struggle to know which icons are available, generate correct SVG code, maintain consistent styles, and organize icons properly. Inline SVGs also consume unnecessary tokens.

Features

• 200,000+ Icons - Search across 150+ icon collections (Lucide, Heroicons, Material Design, etc.)
• Auto-Learning - Remembers which icon collections you use and prioritizes them in future searches
• Project Sync - Icons are written directly to your icons file (.tsx, .ts, .js) instead of pasting SVG into chat (saves tokens!)
• Batch Retrieval - Get multiple icons at once
• Similar Icons - Find the same icon across different collections and styles
• Recent Icons - Quick access to icons you've used before
• Multi-Framework - React, Vue, Svelte, Solid, and raw SVG exports

Manual Installation

Cursor

Add to ~/.cursor/mcp.json:

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

Claude Code (CLI)

Add to ~/.claude/settings.json:

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

Tools

search_icons

Search for icons across 200+ icon libraries.

Search for "arrow" icons
Search for "home" icons in the lucide collection

Parameters:

• query (required): Search query (e.g., 'arrow', 'home', 'user')
• limit (optional): Maximum results (1-999, default: 32)
• prefix (optional): Filter by collection (e.g., 'mdi', 'lucide')
• category (optional): Filter by category

get_icon

Get the SVG code for a specific icon with multiple usage formats.

Get the SVG for mdi:home
Get a URL for mdi:home
Get lucide:arrow-right with size 24

Parameters:

• icon_id (required): Icon ID in format 'prefix:name' (e.g., 'mdi:home')
• color (optional): Icon color (e.g., '#ff0000', 'currentColor')
• size (optional): Icon size in pixels
• format (optional): 'svg' (default) or 'url'

Returns:

• Raw SVG code
• React/JSX component code
• Iconify component usage
• Direct SVG URL (when format: "url")

list_collections

List available icon collections/libraries.

List all icon collections
Search for "material" collections

Parameters:

• category (optional): Filter by category
• search (optional): Search collections by name

recommend_icons

Get icon recommendations for a specific use case.

What icon should I use for a settings button?
Recommend icons for user authentication

Parameters:

• use_case (required): Describe what you need
• style (optional): 'solid', 'outline', or 'any'
• limit (optional): Number of recommendations (1-20)

get_icon_preferences

View your learned icon collection preferences with usage statistics.

Show my icon preferences
What icon collections do I use most?

clear_icon_preferences

Reset all learned icon preferences to start fresh.

Clear my icon preferences
Reset icon preferences

find_similar_icons

Find similar icons or variations of a given icon across different collections and styles.

Find icons similar to lucide:home
What other arrow icons are there like mdi:arrow-right?

Parameters:

• icon_id (required): Icon ID to find variations of
• limit (optional): Maximum number of similar icons (1-50, default: 10)

get_icons

Get multiple icons at once (batch retrieval). More efficient than multiple get_icon calls.

Get these icons: lucide:home, lucide:settings, lucide:user

Parameters:

• icon_ids (required): Array of icon IDs (max 20)
• color (optional): Color for all icons
• size (optional): Size in pixels for all icons

get_recent_icons

View your recently used icons for quick reuse.

Show my recent icons
What icons have I used recently?

Parameters:

• limit (optional): Number of recent icons to show (1-50, default: 20)

sync_icon

Get an icon AND automatically add it to your project's icons file. The recommended way to add icons.

Sync the lucide:home icon to my project
Add a settings icon to my icons file

Parameters:

• icons_file (required): Absolute path to the icons file
• framework (required): 'react', 'vue', 'svelte', 'solid', or 'svg'
• icon_id (required): Icon ID in format 'prefix:name'
• component_name (optional): Custom component name
• color (optional): Icon color
• size (optional): Icon size in pixels

Returns:

• Confirmation that icon was added (or already exists)
• Import statement to use
• Usage example

scan_project_icons

Scan an icons file to see what icons are already available.

What icons are already in my project?
Scan my icons file

Parameters:

• icons_file (required): Absolute path to the icons file

Popular Icon Collections

CLI Commands

npx better-icons              # Run the MCP server (for tool configs)
npx better-icons setup        # Interactive setup wizard
npx better-icons setup -y     # Setup with auto-confirm (global)
npx better-icons setup -s project  # Setup for current project only
npx better-icons config       # Show manual config instructions
npx better-icons --help       # Show help

Options

Scope

• Global: Configures MCP server for all projects (stored in home directory)
• Project: Configures MCP server for current project only (stored in project root)

Development

# Install dependencies
bun install

# Run locally
bun run dev

# Build
bun run build

License

MIT