aria-icons

Tiny CLI + MCP server for Aria Icons. Search 340k+ icons, drop them into your repo as source (no giant dependency), migrate existing icon libraries, and expose the same engine to AI agents.

npx aria-icons search arrow
npx aria-icons add house arrow-up github
npx aria-icons migrate --to lucide --dry-run
npx aria-icons setup

Install

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

Agent skill

npx skills add LeulAria/Aria-Icons

MCP

npx aria-icons setup

Configures Cursor, Claude Code, OpenCode, Windsurf, VS Code, and Google Antigravity.

Or run the server directly:

npx aria-icons mcp

Manual Cursor config (~/.cursor/mcp.json):

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

Remote HTTP MCP (same tools, hosted):

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

Commands

| Command | What it does | |---------|----------------| | search <query> | Search all collections | | get <id> | Print SVG or a framework component | | add <names…> | Write icon source files into the project | | migrate --to <set> | Map existing icon-package imports onto one collection | | doctor | Audit mixed libraries / unused imports | | suggest [src/] | Recommend a consistent set from current usage | | init | Write .aria-icons.json | | setup | Wire MCP into your editor | | config | Print manual MCP snippets | | collections | List collections | | mcp | Stdio MCP server (also the default with no args) |

aria-icons search "shopping cart" --collection lucide --json
aria-icons get lucide:house --format react --size 20
aria-icons add house --framework vue --out-dir src/components/icons
aria-icons migrate --to lucide --dry-run

Icon ids use collection:name (lucide:house, thesvg:github). The CLI only downloads the icons you request.

Development (this package)

From the monorepo root:

bun install
bun run cli:dev -- search house --api http://localhost:3001
bun run cli:build
bun run --cwd packages/cli test

Publish

cd packages/cli
bun run release          # bumpp: commit, tag vX.Y.Z, push
# GitHub Actions publishes to npm on the tag

Manual:

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

License

MIT