LeulAria/Aria-Icons

1.4M open-source SVG icons — searchable, write-as-source CLI, and MCP for AI coding agents.
bash
npx -y aria-icons@latest setup
If this saves you time, a star helps others find it.
## Quick start
bash
npx -y aria-icons@latest setup
# or
bunx aria-icons@latest setup
bash
npm install -g aria-icons
# or
bun add -g aria-icons
| Command | Purpose |
| search | Search all collections |
| get | Print SVG or framework source |
| add | Write icon files into the repo |
| migrate --to | Map existing icon-package imports onto one collection |
| doctor | Audit mixed libraries |
| suggest [src/] | Recommend a consistent set |
| init | Write .aria-icons.json |
| setup | Configure MCP for Cursor / Claude / VS Code / … |
| mcp | Stdio MCP server (default if you run aria-icons with no args) |
Icon ids: collection:name (lucide:house, tabler:arrow-up, thesvg:github).
Full CLI docs: packages/cli/README.md.
### MCP
Local (stdio) — what aria-icons setup writes:
json
"mcpServers": {
"aria-icons": {
"command": "npx",
"args": ["-y", "aria-icons"]
Remote HTTP — same catalog, hosted with the website:
json
"mcpServers": {
"aria-icons": {
"url": "https://icons.leularia.com/api/mcp"
Public REST used by the CLI (tiny payloads, no icon database in the package):
| Endpoint | |
| GET /api/v1/search?q= | Search |
| GET /api/v1/icon?id=lucide:house | One icon |
| GET /api/v1/icons?ids=a,b | Batch |
| GET /api/v1/collections | Collections |
| GET /api/v1/similar?id= | Similar / other sets |
| GET /api/v1/equivalent?id=&to= | Cross-set mapping |
During local development:
bash
ARIAICONSAPI=http://localhost:3001 bun run cli:dev -- search house
## Website (this monorepo)
First, install the dependencies:
bash
bun install
Fetch the brand + Iconify icon sources (one-time, or whenever you want to refresh), then rebuild the search catalog:
bash
cd apps/web
bun run fetch:thesvg # ~6,500 brand logos (~4s)
bun run fetch:iconify -- --all # 200+ Iconify sets (~80s)
bun run generate-icons # build icons-meta.json for search + MCP
Then, from the repo root, run the development server:
bash
bun run dev
Open http://localhost:3001 in your browser. The in-app Contribute Icons page (/contribute) walks through adding a new set.
## Icon Sources
Icons come from three storage backends, all indexed into one catalog:
| Source | Storage | Fetch |
| Vendored sets (Lucide, Tabler, Heroicons, …) | one JSON per set in apps/web/icons/vendored/ | committed to the repo |
| theSVG brand logos (6,500+ brands, variants) | apps/web/icons/thesvg.json | bun run fetch:thesvg (auto-packs) |
| Iconify collections (200+ sets) | one JSON per set in apps/web/icons/iconify/ | bun run fetch:iconify (add -- --all for every set) |
After fetching, rebuild the search catalog:
bash
cd apps/web
bun run generate-icons
This writes public/icons-meta.json (browser + MCP search index with names,
tags, aliases, and categories) and icons-name.json.
## Contributing Icons
Every icon set here was contributed or curated by the community — new sets
and better metadata are always welcome. The in-app guide at
/contribute walks through it, and the
short version is:
1. Fork LeulAria/Aria-Icons and clone your fork.
2. Add SVGs under apps/web/icons/ / (lowercase, hyphenated file names — the file name becomes the icon name).