Back to search
Aria-Icons
SkillGitHub
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
Markdown
[](/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.
- [](https://github.com/LeulAria/Aria-Icons/stargazers)
- [](LICENSE)
- [](https://www.npmjs.com/package/aria-icons)
- [](https://mcpservers.org/servers/leularia/aria-icons)
- [](https://mcprepository.com/leularia/aria-icons)
- <!-- TODO(glama): Uncomment after the server is listed on Glama:
- [](https://glama.ai/mcp/servers/LeulAria/Aria-Icons)
- -->
- # 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](https://github.com/LeulAria/Aria-Icons) helps others find it.
- <!-- TODO: Add a short hero GIF/demo here (agent asks for an icon → MCP search → file appears in the repo).
- 
- -->
- ## 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 <query>` | Search all collections |
- | `get <id>` | Print SVG or framework source |
- | `add <names…>` | Write icon files into the repo |
- | `migrate --to <set>` | 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`](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
- ARIA_ICONS_API=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](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`](http://localhost:3001/contribute) walks through it, and the
- short version is:
- 1. **Fork** [LeulAria/Aria-Icons](https://github.com/LeulAria/Aria-Icons) and clone your fork.
- 2. **Add SVGs** under `apps/web/icons/<your-set-name>/` (lowercase, hyphenated file names — the file name becomes the icon name).
- 3. **Register the set** in `apps/web/src/lib/icon-sets.ts` (id, label, homepage, and whether it's `line` or `solid` style).
- 4. **Pack + rebuild** with `bun run pack:icons -- --delete && bun run generate-icons` inside `apps/web`.
- 5. **Preview** with `bun run dev` — check the sidebar, grid rendering, and search.
- 6. **Open a pull request** against [LeulAria/Aria-Icons](https://github.com/LeulAria/Aria-Icons) mentioning the icon count, source, and license.
- Other ways to contribute:
- - **Brand icons** — contribute upstream to [theSVG](https://github.com/glincker/thesvg), then refresh with `bun run fetch:thesvg`.
- - **Iconify sets** — pull additional collections with `bun run fetch:iconify -- --sets <prefix>`.
- - **Metadata** — better tags/aliases make search smarter; metadata PRs are just as valuable as new icons.
- Only submit icons you have the right to share, and include the license in
- your PR (MIT, CC0, or similarly permissive licenses preferred).
- ## Project Structure
- ```
- aria-icons/
- ├── apps/
- │ └── web/ # Next.js app, catalog, /api/v1, HTTP MCP
- ├── packages/
- │ ├── cli/ # published npm package `aria-icons`
- │ ├── api/ # oRPC layer
- │ └── config/
- ├── Dockerfile # stdio MCP server image (Glama / local)
- └── glama.json # Glama maintainer claim
- ```
- ## Run, build, version, publish
- ```bash
- # Install
- bun install
- # Website
- bun run dev:web # http://localhost:3001
- bun run build # turbo: web + cli
- # CLI against production API
- bun run cli:dev -- search house
- bun run cli:dev -- get lucide:house
- bun run cli:dev -- doctor
- # CLI against local website
- ARIA_ICONS_API=http://localhost:3001 bun run cli:dev -- search house
- # Tests + types
- bun run cli:test
- bun run check-types
- # Version the CLI (bumpp: commit, tag vX.Y.Z, push)
- bun run cli:release
- # GitHub Actions then publishes packages/cli to npm on tag v*
- # Requires repo secret NPM_TOKEN
- ```
- Manual npm publish:
- ```bash
- cd packages/cli
- bun run build
- npm publish --access public
- ```
- Pre-release:
- ```bash
- cd packages/cli
- bunx bumpp prerelease --preid beta --commit --tag --push
- # tag like v0.1.1-beta.0 publishes with npm tag `beta`
- ```
- 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.
- ## Available Scripts
- - `bun run dev`: Start all applications in development mode
- - `bun run build`: Build all applications
- - `bun run check-types`: Check TypeScript types across all apps
- - `bun run cli:dev`: Run the CLI from source
- - `bun run cli:build`: Bundle the CLI for npm
- - `bun run cli:release`: Version, tag, and push the CLI
- Inside `apps/web`:
- - `bun run fetch:thesvg`: Fetch/refresh theSVG brand icons (packs into `icons/thesvg.json`)
- - `bun run fetch:iconify`: Fetch Iconify sets (`-- --sets a,b`, `-- --all`)
- - `bun run pack:icons`: Collapse loose SVG folders into one JSON per set (`-- --delete` removes sources)
- - `bun run generate-icons`: Rebuild the icon search catalog
- ## Licensing
- The **code** in this repository (website, CLI, MCP server) is [MIT](LICENSE) © Leul Aria.
- 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.
- ### Where to look
- | What | Where |
- |------|--------|
- | Per-set `license`, `copyleft`, and `attribution` fields | [`apps/web/src/lib/icon-sets.ts`](apps/web/src/lib/icon-sets.ts) |
- | Round-3 family licence notes (table + per-set files) | [`apps/web/icons/licenses/r3/`](apps/web/icons/licenses/r3/) |
- | Iconify collection licence metadata | [`apps/web/icons/iconify/collections.json`](apps/web/icons/iconify/collections.json) |
- 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.
- ### Attribution (CC-BY / CC-BY-SA)
- 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.
- ### Issues
- 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.
- ## License
- [MIT](LICENSE) © Leul Aria (code). Icons remain under their upstream licenses — see [Licensing](#licensing).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.