better-icons
Skill and MCP server for searching and retrieving icons
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/better-auth-better-icons)HTML
<a href="/listings/better-auth-better-icons"><img src="/api/listings/better-auth-better-icons/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Add Skills
Enable the `better-icons` CLI features in your agent environment (matches all examples below):
npx skills add better-auth/better-icons
Direct CLI Installation
Alternatively, install the CLI globally for direct non-agent use:
# Using npm npm install -g better-icons # Using Bun (faster) bun add -g 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](#manual-installation).
CLI (Direct Usage)
Use the CLI to search and retrieve icons directly from your terminal.
# 1. Search for icons (finds icons across 150+ collections) npx better-icons search arrow --limit 10 npx better-icons search home --prefix lucide # 2. Get icon SVG (outputs raw code or saves to file) npx better-icons get lucide:home > icon.svg npx better-icons get mdi:account --color '#333' --size 24 # 3. JSON output for scripting npx better-icons search settings --json | jq '.icons[:5]' npx better-icons get heroicons:check --json
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 361 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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
- Enable the `better-icons` CLI features in your agent environment (matches all examples below):
- ```bash
- npx skills add better-auth/better-icons
- ```
- ### Direct CLI Installation
- Alternatively, install the CLI globally for direct non-agent use:
- ```bash
- # Using npm
- npm install -g better-icons
- # Using Bun (faster)
- bun add -g better-icons
- ```
- ---
- ### MCP Server (AI Agents)
- Configure the MCP server to enable icon tools in your AI coding agents.
- ```bash
- npx better-icons setup
- ```
- This interactively configures the MCP server for:
- - **Cursor**
- - **Claude Code**
- - **OpenCode**
- - **Windsurf**
- - **VS Code (Copilot)**
- - **Google Antigravity**
- Or [configure manually](#manual-installation).
- ### CLI (Direct Usage)
- Use the CLI to search and retrieve icons directly from your terminal.
- ```bash
- # 1. Search for icons (finds icons across 150+ collections)
- npx better-icons search arrow --limit 10
- npx better-icons search home --prefix lucide
- # 2. Get icon SVG (outputs raw code or saves to file)
- npx better-icons get lucide:home > icon.svg
- npx better-icons get mdi:account --color '#333' --size 24
- # 3. 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`:
- ```json
- {
- "mcpServers": {
- "better-icons": {
- "command": "npx",
- "args": ["-y", "better-icons"]
- }
- }
- }
- ```
- ### Claude Code (CLI)
- Add to `~/.claude/settings.json`:
- ```json
- {
- "mcpServers": {
- "better-icons": {
- "command": "npx",
- "args": ["-y", "better-icons"]
- }
- }
- }
- ```
- ### Google Antigravity
- Add to `~/.gemini/antigravity/mcp_config.json`:
- ```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, 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
- | Prefix | Name | Style | Icons |
- |--------|------|-------|-------|
- | `mdi` | Material Design Icons | Solid | 7,000+ |
- | `lucide` | Lucide Icons | Outline | 1,500+ |
- | `heroicons` | Heroicons | Both | 300+ |
- | `tabler` | Tabler Icons | Outline | 5,000+ |
- | `ph` | Phosphor Icons | Multiple | 9,000+ |
- | `ri` | Remix Icons | Both | 2,800+ |
- | `fa6-solid` | Font Awesome 6 | Solid | 2,000+ |
- | `simple-icons` | Simple Icons | Logos | 3,000+ |
- ## CLI Reference
- ### Search Icons
- Search across 150+ icon collections.
- ```bash
- better-icons search <query> [options]
- ```
- | Option | Description |
- |--------|-------------|
- | `-p, --prefix <prefix>` | Filter by collection (e.g., `lucide`, `mdi`) |
- | `-l, --limit <number>` | Maximum results (default: 32) |
- | `--json` | Output as JSON for scripting |
- ### Get Icon
- Retrieve a single icon's SVG code.
- ```bash
- better-icons get <icon-id> [options]
- ```
- | Option | Description |
- |--------|-------------|
- | `-c, --color <color>` | Icon color (e.g., `#ff0000`, `currentColor`) |
- | `-s, --size <pixels>` | Icon size in pixels |
- | `--json` | Output as JSON with metadata |
- The icon ID format is `prefix:name` (e.g., `lucide:home`, `mdi:arrow-right`).
- ### Setup Commands
- ```bash
- better-icons setup # Interactive setup wizard
- better-icons setup -y # Auto-confirm (global scope)
- better-icons setup -s project # Setup for current project only
- better-icons config # Show manual config instructions
- ```
- | Option | Description |
- |--------|-------------|
- | `-y, --yes` | Skip confirmation prompts |
- | `-a, --agent <agents...>` | Specify agents (cursor, claude-code, opencode, windsurf, vscode, antigravity) |
- | `-s, --scope <scope>` | Config scope: `global` (default) or `project` |
- ## Development
- ```bash
- # Install dependencies
- bun install
- # Run locally
- bun run dev
- # Build
- bun run build
- ```
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.