better-icons

To enable better-icons features within an AI agent environment (such as Cursor, Claude Code, etc.), use the skills add command.

npx skills add better-auth/better-icons

You can install better-icons globally to make the CLI available on your $PATH, or run it without installation using npx or bunx. Global installation is recommended, especially for AI agents.

Global Installation

# Using npm
npm install -g better-icons

# Using Bun (faster)
bun add -g better-icons

Run without installing

# Using npx
npx better-icons search arrow --limit 10

# Using bunx
bunx better-icons search arrow --limit 10

You can install the better-icons CLI globally for direct use in your terminal using either npm or bun.

Using npm

npm install -g better-icons

Using Bun (faster)

bun add -g better-icons

To enable AI agents (like Cursor or Claude Code) to use better-icons tools, use the setup command. This configures the Model Context Protocol (MCP) server.

Command Syntax: better-icons setup [-a cursor,claude-code] [-s global|project]

Available MCP Tools:

• search_icons: Search across all libraries
• get_icon: Get single icon SVG
• get_icons: Batch retrieve multiple icons
• list_collections: Browse available icon sets
• recommend_icons: Smart recommendations for use cases
• find_similar_icons: Find variations across collections
• sync_icon: Add icon to project file
• scan_project_icons: List icons in project

When setting up Better Icons for AI agents, you can choose the scope of the configuration:

1. Global Scope (global)

   • Makes the icon search capabilities available across all your projects.
   • Required for the antigravity agent.
   • Uses the agent's standard global configuration path.

2. Project Scope (project)

   • Limits the icon capabilities to the current project only.
   • Useful for keeping project-specific tools isolated.
   • Uses the agent's project-specific configuration path.

Constraint: If you attempt to add antigravity using the project scope, the setup will fail. You must use -s global or remove the antigravity flag.

To use better-icons as a Model Context Protocol (MCP) server in AI coding environments, you can use the following configuration objects. These are designed to be added to your agent's MCP settings file.

Standard MCP Configuration

Use this for standard MCP-compliant agents (like Claude Code or Windsurf):

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

OpenCode MCP Configuration

If you are using OpenCode, use the specific local type configuration:

{
  "better-icons": {
    "type": "local",
    "command": ["npx", "-y", "better-icons"],
    "enabled": true
  }
}

To use better-icons with AI agents (such as Cursor, Claude Desktop, VS Code, Windsurf, OpenCode, or Google Antigravity), you must add the generated MCP (Model Context Protocol) configuration to your agent's specific configuration file.

Running the config command provides the exact JSON snippets required for:

1. Standard MCP Servers: For most desktop AI agents.
2. OpenCode MCP: Specifically for OpenCode environments.

Common configuration file locations include:

• Cursor: ~/.cursor/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• VS Code: ~/.vscode/mcp.json
• Windsurf: ~/.windsurf/mcp.json
• OpenCode: ~/.config/opencode/opencode.json
• Google Antigravity: ~/.gemini/antigravity/mcp_config.json

Use the search command to find icons across 150+ collections. You can filter by prefix (collection name) and limit the number of results.

# Search for icons with a limit
npx better-icons search arrow --limit 10

# Search within a specific collection (e.g., lucide)
npx better-icons search home --prefix lucide

# Output results as JSON for scripting
npx better-icons search settings --json | jq '.icons[:5]'

The search command supports a -d (or --download) flag to automatically save all found icons as SVG files to a specified directory.

Command Syntax: better-icons search <query> -d [dir] [--color <color>] [--size <px>]

Examples:

# Save results to the default ./icons/ directory
better-icons search arrow -d

# Save results to a specific directory
better-icons search check -d ./my-icons

# Batch download with specific color and size
better-icons search star -d -c '#000' -s 24 --limit 64

Use the get command to retrieve the raw SVG code for a specific icon. You can specify the color and size directly in the command.

Icon ID Format: Icons must be referenced using the prefix:name format (e.g., lucide:home, mdi:arrow-right).

Command Syntax: better-icons get <icon-id> [--color <color>] [--size <px>] [--json]

Examples:

# Output SVG to stdout and redirect to a file
better-icons get lucide:home > icon.svg

# Get icon with specific color and JSON output
better-icons get mdi:home --color '#333' --json

Use the search command to find icons across 200+ libraries. You can filter by prefix, limit the number of results, or request JSON output for scripting.

Command Syntax: better-icons search <query> [--prefix <prefix>] [--limit <n>] [--json]

Examples:

# Search for 'arrow' with a limit of 10
better-icons search arrow --limit 10

# Search for 'home' and pipe JSON output to jq
better-icons search home --json | jq '.icons[0]'