Skip to content
Back to search

Aria-Icons

MCP server for 1M+ SVG 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/leularia--aria-icons/badge.svg)](/listings/leularia--aria-icons)

HTML

<a href="/listings/leularia--aria-icons"><img src="/api/listings/leularia--aria-icons/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 270 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![GitHub stars](https://img.shields.io/github/stars/LeulAria/Aria-Icons?style=flat)](https://github.com/LeulAria/Aria-Icons/stargazers)
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  3. [![npm](https://img.shields.io/npm/v/aria-icons)](https://www.npmjs.com/package/aria-icons)
  4. [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/leularia/aria-icons)
  5. [![MCP Repository](https://img.shields.io/badge/Listed%20on-MCP%20Repository-5C6BC0)](https://mcprepository.com/leularia/aria-icons)
  6. <!-- TODO(glama): Uncomment after the server is listed on Glama:
  7. [![Glama score](https://glama.ai/mcp/servers/LeulAria/Aria-Icons/badges/score.svg)](https://glama.ai/mcp/servers/LeulAria/Aria-Icons)
  8. -->
  9. # Aria Icons
  10. **1.4M open-source SVG icons — searchable, write-as-source CLI, and MCP for AI coding agents.**
  11. ```bash
  12. npx -y aria-icons@latest setup
  13. ```
  14. If this saves you time, a [star](https://github.com/LeulAria/Aria-Icons) helps others find it.
  15. <!-- TODO: Add a short hero GIF/demo here (agent asks for an icon → MCP search → file appears in the repo).
  16. ![Aria Icons demo](docs/demo.gif)
  17. -->
  18. ## Quick start
  19. ```bash
  20. npx -y aria-icons@latest setup
  21. # or
  22. bunx aria-icons@latest setup
  23. ```
  24. ```bash
  25. npm install -g aria-icons
  26. # or
  27. bun add -g aria-icons
  28. ```
  29. | Command | Purpose |
  30. |---------|---------|
  31. | `search <query>` | Search all collections |
  32. | `get <id>` | Print SVG or framework source |
  33. | `add <names…>` | Write icon files into the repo |
  34. | `migrate --to <set>` | Map existing icon-package imports onto one collection |
  35. | `doctor` | Audit mixed libraries |
  36. | `suggest [src/]` | Recommend a consistent set |
  37. | `init` | Write `.aria-icons.json` |
  38. | `setup` | Configure MCP for Cursor / Claude / VS Code / … |
  39. | `mcp` | Stdio MCP server (default if you run `aria-icons` with no args) |
  40. Icon ids: `collection:name` (`lucide:house`, `tabler:arrow-up`, `thesvg:github`).
  41. Full CLI docs: [`packages/cli/README.md`](packages/cli/README.md).
  42. ### MCP
  43. **Local (stdio)** — what `aria-icons setup` writes:
  44. ```json
  45. {
  46. "mcpServers": {
  47. "aria-icons": {
  48. "command": "npx",
  49. "args": ["-y", "aria-icons"]
  50. }
  51. }
  52. }
  53. ```
  54. **Remote HTTP** — same catalog, hosted with the website:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "aria-icons": {
  59. "url": "https://icons.leularia.com/api/mcp"
  60. }
  61. }
  62. }
  63. ```
  64. Public REST used by the CLI (tiny payloads, no icon database in the package):
  65. | Endpoint | |
  66. |----------|--|
  67. | `GET /api/v1/search?q=` | Search |
  68. | `GET /api/v1/icon?id=lucide:house` | One icon |
  69. | `GET /api/v1/icons?ids=a,b` | Batch |
  70. | `GET /api/v1/collections` | Collections |
  71. | `GET /api/v1/similar?id=` | Similar / other sets |
  72. | `GET /api/v1/equivalent?id=&to=` | Cross-set mapping |
  73. During local development:
  74. ```bash
  75. ARIA_ICONS_API=http://localhost:3001 bun run cli:dev -- search house
  76. ```
  77. ## Website (this monorepo)
  78. First, install the dependencies:
  79. ```bash
  80. bun install
  81. ```
  82. Fetch the brand + Iconify icon sources (one-time, or whenever you want to refresh), then rebuild the search catalog:
  83. ```bash
  84. cd apps/web
  85. bun run fetch:thesvg # ~6,500 brand logos (~4s)
  86. bun run fetch:iconify -- --all # 200+ Iconify sets (~80s)
  87. bun run generate-icons # build icons-meta.json for search + MCP
  88. ```
  89. Then, from the repo root, run the development server:
  90. ```bash
  91. bun run dev
  92. ```
  93. Open [http://localhost:3001](http://localhost:3001) in your browser. The in-app **Contribute Icons** page (`/contribute`) walks through adding a new set.
  94. ## Icon Sources
  95. Icons come from three storage backends, all indexed into one catalog:
  96. | Source | Storage | Fetch |
  97. | --- | --- | --- |
  98. | Vendored sets (Lucide, Tabler, Heroicons, …) | one JSON per set in `apps/web/icons/vendored/` | committed to the repo |
  99. | theSVG brand logos (6,500+ brands, variants) | `apps/web/icons/thesvg.json` | `bun run fetch:thesvg` (auto-packs) |
  100. | Iconify collections (200+ sets) | one JSON per set in `apps/web/icons/iconify/` | `bun run fetch:iconify` (add `-- --all` for every set) |
  101. After fetching, rebuild the search catalog:
  102. ```bash
  103. cd apps/web
  104. bun run generate-icons
  105. ```
  106. This writes `public/icons-meta.json` (browser + MCP search index with names,
  107. tags, aliases, and categories) and `icons-name.json`.
  108. ## Contributing Icons
  109. Every icon set here was contributed or curated by the community — new sets
  110. and better metadata are always welcome. The in-app guide at
  111. [`/contribute`](http://localhost:3001/contribute) walks through it, and the
  112. short version is:
  113. 1. **Fork** [LeulAria/Aria-Icons](https://github.com/LeulAria/Aria-Icons) and clone your fork.
  114. 2. **Add SVGs** under `apps/web/icons/<your-set-name>/` (lowercase, hyphenated file names — the file name becomes the icon name).
  115. 3. **Register the set** in `apps/web/src/lib/icon-sets.ts` (id, label, homepage, and whether it's `line` or `solid` style).
  116. 4. **Pack + rebuild** with `bun run pack:icons -- --delete && bun run generate-icons` inside `apps/web`.
  117. 5. **Preview** with `bun run dev` — check the sidebar, grid rendering, and search.
  118. 6. **Open a pull request** against [LeulAria/Aria-Icons](https://github.com/LeulAria/Aria-Icons) mentioning the icon count, source, and license.
  119. Other ways to contribute:
  120. - **Brand icons** — contribute upstream to [theSVG](https://github.com/glincker/thesvg), then refresh with `bun run fetch:thesvg`.
  121. - **Iconify sets** — pull additional collections with `bun run fetch:iconify -- --sets <prefix>`.
  122. - **Metadata** — better tags/aliases make search smarter; metadata PRs are just as valuable as new icons.
  123. Only submit icons you have the right to share, and include the license in
  124. your PR (MIT, CC0, or similarly permissive licenses preferred).
  125. ## Project Structure
  126. ```
  127. aria-icons/
  128. ├── apps/
  129. │ └── web/ # Next.js app, catalog, /api/v1, HTTP MCP
  130. ├── packages/
  131. │ ├── cli/ # published npm package `aria-icons`
  132. │ ├── api/ # oRPC layer
  133. │ └── config/
  134. ├── Dockerfile # stdio MCP server image (Glama / local)
  135. └── glama.json # Glama maintainer claim
  136. ```
  137. ## Run, build, version, publish
  138. ```bash
  139. # Install
  140. bun install
  141. # Website
  142. bun run dev:web # http://localhost:3001
  143. bun run build # turbo: web + cli
  144. # CLI against production API
  145. bun run cli:dev -- search house
  146. bun run cli:dev -- get lucide:house
  147. bun run cli:dev -- doctor
  148. # CLI against local website
  149. ARIA_ICONS_API=http://localhost:3001 bun run cli:dev -- search house
  150. # Tests + types
  151. bun run cli:test
  152. bun run check-types
  153. # Version the CLI (bumpp: commit, tag vX.Y.Z, push)
  154. bun run cli:release
  155. # GitHub Actions then publishes packages/cli to npm on tag v*
  156. # Requires repo secret NPM_TOKEN
  157. ```
  158. Manual npm publish:
  159. ```bash
  160. cd packages/cli
  161. bun run build
  162. npm publish --access public
  163. ```
  164. Pre-release:
  165. ```bash
  166. cd packages/cli
  167. bunx bumpp prerelease --preid beta --commit --tag --push
  168. # tag like v0.1.1-beta.0 publishes with npm tag `beta`
  169. ```
  170. Website deploy is unchanged (Vercel / your current host for `apps/web`). After deploy, `/api/v1/*` and `/api/mcp` are what the CLI and remote MCP use.
  171. ## Available Scripts
  172. - `bun run dev`: Start all applications in development mode
  173. - `bun run build`: Build all applications
  174. - `bun run check-types`: Check TypeScript types across all apps
  175. - `bun run cli:dev`: Run the CLI from source
  176. - `bun run cli:build`: Bundle the CLI for npm
  177. - `bun run cli:release`: Version, tag, and push the CLI
  178. Inside `apps/web`:
  179. - `bun run fetch:thesvg`: Fetch/refresh theSVG brand icons (packs into `icons/thesvg.json`)
  180. - `bun run fetch:iconify`: Fetch Iconify sets (`-- --sets a,b`, `-- --all`)
  181. - `bun run pack:icons`: Collapse loose SVG folders into one JSON per set (`-- --delete` removes sources)
  182. - `bun run generate-icons`: Rebuild the icon search catalog
  183. ## Licensing
  184. The **code** in this repository (website, CLI, MCP server) is [MIT](LICENSE) © Leul Aria.
  185. The **icons** come from many upstream sets and keep their own licenses. Across the catalog you will find MIT, Apache-2.0, ISC, BSD, CC0, CC-BY, CC-BY-SA, GPL/LGPL, MPL, and similar terms — not a single uniform icon license.
  186. ### Where to look
  187. | What | Where |
  188. |------|--------|
  189. | Per-set `license`, `copyleft`, and `attribution` fields | [`apps/web/src/lib/icon-sets.ts`](apps/web/src/lib/icon-sets.ts) |
  190. | Round-3 family licence notes (table + per-set files) | [`apps/web/icons/licenses/r3/`](apps/web/icons/licenses/r3/) |
  191. | Iconify collection licence metadata | [`apps/web/icons/iconify/collections.json`](apps/web/icons/iconify/collections.json) |
  192. Sets marked `copyleft: true` (for example GPL, LGPL, CC-BY-SA, MPL) may require sharing modifications under the same terms when you redistribute derived works — check the upstream licence before shipping.
  193. ### Attribution (CC-BY / CC-BY-SA)
  194. When a set records an `attribution` URL or text in `icon-sets.ts`, include that credit when you use those icons in a way that requires attribution (typical for CC-BY and CC-BY-SA). Prefer linking the upstream project page listed in the set metadata.
  195. ### Issues
  196. If you believe an icon set is mis-licensed or should be removed, open a [GitHub issue](https://github.com/LeulAria/Aria-Icons/issues/new) with the set id and evidence. We take takedown requests seriously.
  197. ## License
  198. [MIT](LICENSE) © Leul Aria (code). Icons remain under their upstream licenses — see [Licensing](#licensing).

Ratings and comments

Sign in to rate this skill.

Sign in

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