Stop installing giant icon packages — write SVGs as source with a CLI + MCP

arialus — Wed, 23 Sep 2026 04:42:04 +0000

The pain nobody admits in the PR

You need a house icon, an arrow, a settings gear, and the GitHub logo.

So you install Lucide. Then someone on the team already used Tabler. The marketing site copied Heroicons. Brand marks came from a random SVG dump. Six months later:

node_modules carries thousands of icons you never render
imports disagree on naming (House vs IconHome vs home)
agents invent Lucide paths that don’t exist
design asks for “the same icon but from that other set”

Lucide, Tabler, Heroicons, Feather, Remix theyre excellent art. Theyre a weak delivery model when your app only needs twelve icons from four families.

I wanted something closer to a package manager: search a huge catalog, pull only what I need, commit the SVG as source, and let Cursor / Claude use the same engine without hallucinating.

That’s Aria Icons.

What Aria Icons actually is

Not another Lucide clone. Peers worth comparing: Iconify (catalog) and better-icons. Aria’s bet is:

Browser over ~340k SVGs Lucide, Tabler, Heroicons, Feather, Remix, brands via theSVG, Iconify-backed collections, and more
CLI (npx aria-icons) that searches a hosted API and writes icons into your repo as source — no fat icon dependency
MCP for Cursor / Claude — local stdio or remote HTTP — so agents search and fetch the same catalog

Site: https://icons.leularia.com

Repo: https://github.com/LeulAria/Aria-Icons (MIT)

npm: aria-icons

Quickstart (concrete, copy-paste)

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

Search the catalog:

npx aria-icons search house

Print one icon (SVG or framework-oriented output depending on flags/docs):

npx aria-icons get lucide:house

Add icons as files in the project:

npx aria-icons add lucide:house tabler:arrow-up thesvg:github

Ids look like collection:name — e.g. lucide:house, tabler:arrow-up, thesvg:github.

When you’re already in mixed-library hell:

npx aria-icons doctor
npx aria-icons suggest src/
npx aria-icons migrate --to lucide

The CLI stays tiny on purpose. It talks to the Aria Icons API and only downloads the icons you request. Your lockfile doesn’t inherit 340k SVGs.

Give agents a real catalog (MCP)

Coding agents are great at wiring components and terrible at remembering every icon name across every set. Aria Icons MCP exposes search/fetch over the same index the CLI uses.

Remote HTTP (hosted with the site):

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

Local stdio (what aria-icons setup configures for Cursor / Claude / VS Code-style clients):

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

Typical loop that works well in practice:

Ask the agent to search for an icon via MCP
Review the pick in the browser if you care about aesthetics
aria-icons add … so the SVG lands in source control

Agents get truth; humans keep commit hygiene.

How this differs from Lucide / Iconify / “just copy SVG”

Approach	Strength	Weakness
Single set package (Lucide, etc.)	Cohesive style, great DX for one family	Fat install; multi-set reality breaks the model
Iconify	Huge catalog, flexible	You still need a workflow for “icons as source in this repo” + agent tooling
Manual SVG paste	Zero dependency	Drift, duplicates, no search, agents invent junk
Aria Icons	Catalog + write-as-source CLI + MCP	You’re choosing a workflow, not a single aesthetic brand

Positioning in one line: icon package manager + agent surface, not an art set competing with Lucide’s drawings.

Architecture sketch (why the CLI isn’t a megapackage)

The interesting part is the shape:

Fat index on the server — search metadata for ~340k icons (vendored sets, Iconify collections, brand logos)
Thin client — npm package aria-icons is a CLI + MCP entrypoint, not the database
Write path — add materializes only chosen icons into your tree
Audit path — doctor / suggest / migrate for teams that already mixed libraries

Public REST used by the CLI (tiny payloads): search, icon by id, batch, collections, similar, equivalent/cross-set mapping. MCP rides the same catalog.

That means:

CI doesn’t download an icon universe
design-system PRs review actual SVG files
agents and humans share one source of truth

A realistic workflow for a design system

Open icons.leularia.com and search visually when taste matters
Standardize on ids (lucide:… etc.) in tickets
Engineers run aria-icons add (or let MCP propose, then add)
Occasionally run doctor on src/ before a release
Use migrate --to <set> when consolidating

You’re not forbidden from using Lucide React components forever — you’re free to stop pretending one package covers every brand mark and every one-off.

Open source details

License: MIT
Contribute new sets via the in-app /contribute flow (and PRs)
Brand logos refresh from theSVG; Iconify sets can be fetched/indexed into the catalog

If you maintain icon metadata, tags, and aliases — those PRs matter as much as new drawings. Search quality is the product.

What I’m looking for feedback on

CLI UX: is migrate / doctor / suggest the right surface, or too much?
MCP tools: what should agents get next (similar icons, framework wrappers, Figma-ish naming)?
Messaging: does package manager for icons” land, or do people still hear another icon set”?

Try it, then decide

npx -y aria-icons@latest setup
npx aria-icons search house
npx aria-icons add lucide:house

Site: https://icons.leularia.com
GitHub: https://github.com/LeulAria/Aria-Icons

If the workflow sticks after you try it, starring the repo helps other developers discover it. If it doesn’t, tell me why in the comments — that feedback is more useful than a polite star.

DEV Community: arialus