MCP server for 340k SVG icons

Aria Icons, an open-source project by LeulAria, has released a Model Context Protocol (MCP) server and command-line interface (CLI) that provides access to over 340,000 SVG icons from multiple collections, including Lucide, Tabler, Heroicons, theSVG brand logos, and 200+ Iconify sets. The tool allows developers to search, customize, and integrate icons directly into their codebases, with commands for adding icons, migrating between icon libraries, and auditing mixed sets, and it supports local stdio and remote HTTP MCP configurations for AI agents in Cursor, Claude, and VS Code.

340,000+ SVG icons — searchable, customizable, and a package manager for your icon codebase. Website + API + CLI + MCP. Find any icon, write it into the project as source no giant dependency , migrate mixed icon libraries, and let AI agents use the same engine. Repo: github.com/LeulAria/Aria-Icons https://github.com/LeulAria/Aria-Icons npx -y aria-icons@latest setup or bunx aria-icons@latest setup or curl -fsSL https://icons.leularia.com/install.sh | bash The npm package name is aria-icons verified unused on the registry at the time of adding the CLI . The CLI is tiny: it talks to the Aria Icons API and only downloads the icons you request. npx -y aria-icons@latest setup bunx aria-icons@latest setup curl -fsSL https://icons.leularia.com/install.sh | 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 /LeulAria/Aria-Icons/blob/main/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 : | 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: 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 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: | 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: 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 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 . aria-icons/ ├── apps/ │ └── web/ Next.js app, catalog, /api/v1, HTTP MCP ├── packages/ │ ├── cli/ published npm package aria-icons │ ├── api/ oRPC layer │ └── config/ 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