Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/better-auth-better-icons/badge.svg)](/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

i

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)

  1. # Better Icons
  2. Search and retrieve 200,000+ icons from 150+ icon collections. Works as an MCP server for AI agents or CLI tool.
  3. ## Quick Start
  4. ### Add Skills
  5. Enable the `better-icons` CLI features in your agent environment (matches all examples below):
  6. ```bash
  7. npx skills add better-auth/better-icons
  8. ```
  9. ### Direct CLI Installation
  10. Alternatively, install the CLI globally for direct non-agent use:
  11. ```bash
  12. # Using npm
  13. npm install -g better-icons
  14. # Using Bun (faster)
  15. bun add -g better-icons
  16. ```
  17. ---
  18. ### MCP Server (AI Agents)
  19. Configure the MCP server to enable icon tools in your AI coding agents.
  20. ```bash
  21. npx better-icons setup
  22. ```
  23. This interactively configures the MCP server for:
  24. - **Cursor**
  25. - **Claude Code**
  26. - **OpenCode**
  27. - **Windsurf**
  28. - **VS Code (Copilot)**
  29. - **Google Antigravity**
  30. Or [configure manually](#manual-installation).
  31. ### CLI (Direct Usage)
  32. Use the CLI to search and retrieve icons directly from your terminal.
  33. ```bash
  34. # 1. Search for icons (finds icons across 150+ collections)
  35. npx better-icons search arrow --limit 10
  36. npx better-icons search home --prefix lucide
  37. # 2. Get icon SVG (outputs raw code or saves to file)
  38. npx better-icons get lucide:home > icon.svg
  39. npx better-icons get mdi:account --color '#333' --size 24
  40. # 3. JSON output for scripting
  41. npx better-icons search settings --json | jq '.icons[:5]'
  42. npx better-icons get heroicons:check --json
  43. ```
  44. ## Why?
  45. 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.
  46. ## Features
  47. - **200,000+ Icons** - Search across 150+ icon collections (Lucide, Heroicons, Material Design, etc.)
  48. - **Auto-Learning** - Remembers which icon collections you use and prioritizes them in future searches
  49. - **Project Sync** - Icons are written directly to your icons file (`.tsx`, `.ts`, `.js`) instead of pasting SVG into chat (saves tokens!)
  50. - **Batch Retrieval** - Get multiple icons at once
  51. - **Similar Icons** - Find the same icon across different collections and styles
  52. - **Recent Icons** - Quick access to icons you've used before
  53. - **Multi-Framework** - React, Vue, Svelte, Solid, and raw SVG exports
  54. ## Manual Installation
  55. ### Cursor
  56. Add to `~/.cursor/mcp.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "better-icons": {
  61. "command": "npx",
  62. "args": ["-y", "better-icons"]
  63. }
  64. }
  65. }
  66. ```
  67. ### Claude Code (CLI)
  68. Add to `~/.claude/settings.json`:
  69. ```json
  70. {
  71. "mcpServers": {
  72. "better-icons": {
  73. "command": "npx",
  74. "args": ["-y", "better-icons"]
  75. }
  76. }
  77. }
  78. ```
  79. ### Google Antigravity
  80. Add to `~/.gemini/antigravity/mcp_config.json`:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "better-icons": {
  85. "command": "npx",
  86. "args": ["-y", "better-icons"]
  87. }
  88. }
  89. }
  90. ```
  91. ## MCP Tools
  92. The following tools are available when using the MCP server with AI agents.
  93. ### `search_icons`
  94. Search for icons across 150+ icon collections.
  95. ```
  96. Search for "arrow" icons
  97. Search for "home" icons in the lucide collection
  98. ```
  99. **Parameters:**
  100. - `query` (required): Search query (e.g., 'arrow', 'home', 'user')
  101. - `limit` (optional): Maximum results (1-999, default: 32)
  102. - `prefix` (optional): Filter by collection (e.g., 'mdi', 'lucide')
  103. - `category` (optional): Filter by category
  104. ### `get_icon`
  105. Get the SVG code for a specific icon with multiple usage formats.
  106. ```
  107. Get the SVG for mdi:home
  108. Get a URL for mdi:home
  109. Get lucide:arrow-right with size 24
  110. ```
  111. **Parameters:**
  112. - `icon_id` (required): Icon ID in format 'prefix:name' (e.g., 'mdi:home')
  113. - `color` (optional): Icon color (e.g., '#ff0000', 'currentColor')
  114. - `size` (optional): Icon size in pixels
  115. - `format` (optional): 'svg' (default) or 'url'
  116. **Returns:**
  117. - Raw SVG code
  118. - React/JSX component code
  119. - Iconify component usage
  120. - Direct SVG URL (when `format: "url"`)
  121. ### `list_collections`
  122. List available icon collections/libraries.
  123. ```
  124. List all icon collections
  125. Search for "material" collections
  126. ```
  127. **Parameters:**
  128. - `category` (optional): Filter by category
  129. - `search` (optional): Search collections by name
  130. ### `recommend_icons`
  131. Get icon recommendations for a specific use case.
  132. ```
  133. What icon should I use for a settings button?
  134. Recommend icons for user authentication
  135. ```
  136. **Parameters:**
  137. - `use_case` (required): Describe what you need
  138. - `style` (optional): 'solid', 'outline', or 'any'
  139. - `limit` (optional): Number of recommendations (1-20)
  140. ### `get_icon_preferences`
  141. View your learned icon collection preferences with usage statistics.
  142. ```
  143. Show my icon preferences
  144. What icon collections do I use most?
  145. ```
  146. ### `clear_icon_preferences`
  147. Reset all learned icon preferences to start fresh.
  148. ```
  149. Clear my icon preferences
  150. Reset icon preferences
  151. ```
  152. ### `find_similar_icons`
  153. Find similar icons or variations of a given icon across different collections and styles.
  154. ```
  155. Find icons similar to lucide:home
  156. What other arrow icons are there like mdi:arrow-right?
  157. ```
  158. **Parameters:**
  159. - `icon_id` (required): Icon ID to find variations of
  160. - `limit` (optional): Maximum number of similar icons (1-50, default: 10)
  161. ### `get_icons`
  162. Get multiple icons at once (batch retrieval). More efficient than multiple `get_icon` calls.
  163. ```
  164. Get these icons: lucide:home, lucide:settings, lucide:user
  165. ```
  166. **Parameters:**
  167. - `icon_ids` (required): Array of icon IDs (max 20)
  168. - `color` (optional): Color for all icons
  169. - `size` (optional): Size in pixels for all icons
  170. ### `get_recent_icons`
  171. View your recently used icons for quick reuse.
  172. ```
  173. Show my recent icons
  174. What icons have I used recently?
  175. ```
  176. **Parameters:**
  177. - `limit` (optional): Number of recent icons to show (1-50, default: 20)
  178. ### `sync_icon`
  179. Get an icon AND automatically add it to your project's icons file. The recommended way to add icons.
  180. ```
  181. Sync the lucide:home icon to my project
  182. Add a settings icon to my icons file
  183. ```
  184. **Parameters:**
  185. - `icons_file` (required): Absolute path to the icons file
  186. - `framework` (required): 'react', 'vue', 'svelte', 'solid', or 'svg'
  187. - `icon_id` (required): Icon ID in format 'prefix:name'
  188. - `component_name` (optional): Custom component name
  189. - `color` (optional): Icon color
  190. - `size` (optional): Icon size in pixels
  191. **Returns:**
  192. - Confirmation that icon was added (or already exists)
  193. - Import statement to use
  194. - Usage example
  195. ### `scan_project_icons`
  196. Scan an icons file to see what icons are already available.
  197. ```
  198. What icons are already in my project?
  199. Scan my icons file
  200. ```
  201. **Parameters:**
  202. - `icons_file` (required): Absolute path to the icons file
  203. ## Popular Icon Collections
  204. | Prefix | Name | Style | Icons |
  205. |--------|------|-------|-------|
  206. | `mdi` | Material Design Icons | Solid | 7,000+ |
  207. | `lucide` | Lucide Icons | Outline | 1,500+ |
  208. | `heroicons` | Heroicons | Both | 300+ |
  209. | `tabler` | Tabler Icons | Outline | 5,000+ |
  210. | `ph` | Phosphor Icons | Multiple | 9,000+ |
  211. | `ri` | Remix Icons | Both | 2,800+ |
  212. | `fa6-solid` | Font Awesome 6 | Solid | 2,000+ |
  213. | `simple-icons` | Simple Icons | Logos | 3,000+ |
  214. ## CLI Reference
  215. ### Search Icons
  216. Search across 150+ icon collections.
  217. ```bash
  218. better-icons search <query> [options]
  219. ```
  220. | Option | Description |
  221. |--------|-------------|
  222. | `-p, --prefix <prefix>` | Filter by collection (e.g., `lucide`, `mdi`) |
  223. | `-l, --limit <number>` | Maximum results (default: 32) |
  224. | `--json` | Output as JSON for scripting |
  225. ### Get Icon
  226. Retrieve a single icon's SVG code.
  227. ```bash
  228. better-icons get <icon-id> [options]
  229. ```
  230. | Option | Description |
  231. |--------|-------------|
  232. | `-c, --color <color>` | Icon color (e.g., `#ff0000`, `currentColor`) |
  233. | `-s, --size <pixels>` | Icon size in pixels |
  234. | `--json` | Output as JSON with metadata |
  235. The icon ID format is `prefix:name` (e.g., `lucide:home`, `mdi:arrow-right`).
  236. ### Setup Commands
  237. ```bash
  238. better-icons setup # Interactive setup wizard
  239. better-icons setup -y # Auto-confirm (global scope)
  240. better-icons setup -s project # Setup for current project only
  241. better-icons config # Show manual config instructions
  242. ```
  243. | Option | Description |
  244. |--------|-------------|
  245. | `-y, --yes` | Skip confirmation prompts |
  246. | `-a, --agent <agents...>` | Specify agents (cursor, claude-code, opencode, windsurf, vscode, antigravity) |
  247. | `-s, --scope <scope>` | Config scope: `global` (default) or `project` |
  248. ## Development
  249. ```bash
  250. # Install dependencies
  251. bun install
  252. # Run locally
  253. bun run dev
  254. # Build
  255. bun run build
  256. ```
  257. ## License
  258. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.