Better Icons MCP Server

Better Icons

Search and retrieve 200,000+ icons from 150+ icon collections. Works as an MCP server for AI agents or CLI tool.

Quick Start

Add SKills

You can enable the underlying icons cli usage using skills

npx add-skill better-auth/better-icons

MCP Server (AI Agents)

Configure the MCP server to enable icon tools in your AI coding agents.

npx better-icons setup

This interactively configures the MCP server for:

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

Or configure manually.

CLI (Direct Usage)

Use the CLI to search and retrieve icons directly from your terminal.

# Search for icons
npx better-icons search arrow
npx better-icons search home --prefix lucide --limit 10

# Get icon SVG (outputs to stdout)
npx better-icons get lucide:home > icon.svg
npx better-icons get mdi:account --color '#333' --size 24

# JSON output for scripting
npx better-icons search settings --json | jq '.icons[:5]'
npx better-icons get heroicons:check --json

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"]
    }
  }
}

Google Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

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

MCP Tools

The following tools are available when using the MCP server with AI agents.

`search_icons`

Search for icons across 150+ icon collections.

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,