Aria Icons

1.4M open-source SVG icons — searchable, write-as-source CLI, and MCP for AI coding agents.

npx -y aria-icons@latest setup

If this saves you time, a star helps others find it.

npx -y aria-icons@latest setup
# or
bunx aria-icons@latest setup

npm install -g aria-icons
# or
bun add -g aria-icons

Icon ids: collection:name (lucide:house, tabler:arrow-up, thesvg:github).

Full CLI docs: packages/cli/README.md.

Local (stdio) — what aria-icons setup writes:

{
  "mcpServers": {
    "aria-icons": {
      "command": "npx",
      "args": ["-y", "aria-icons"]
    }
  }
}

Remote HTTP — same catalog, hosted with the website:

{
  "mcpServers": {
    "aria-icons": {
      "url": "https://icons.leularia.com/api/mcp"
    }
  }
}

Public REST used by the CLI (tiny payloads, no icon database in the package):

During local development:

ARIA_ICONS_API=http://localhost:3001 bun run cli:dev -- search house

First, install the dependencies:

bun install

Fetch the brand + Iconify icon sources (one-time, or whenever you want to refresh), then rebuild the search catalog:

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:

bun run dev

Open http://localhost:3001 in your browser. The in-app Contribute Icons page (/contribute) walks through adding a new set.

Icons come from three storage backends, all indexed into one catalog:

After fetching, rebuild the search catalog:

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.

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/<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 mentioning the icon count, source, and license.

Other ways to contribute:

• Brand icons — contribute upstream to 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).

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

# 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:

cd packages/cli
bun run build
npm publish --access public

Pre-release:

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.

• 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

The code in this repository (website, CLI, MCP server) is MIT © 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.

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.

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.

If you believe an icon set is mis-licensed or should be removed, open a GitHub issue with the set id and evidence. We take takedown requests seriously.

MIT © Leul Aria (code). Icons remain under their upstream licenses — see Licensing.