What is Aria Icons MCP?
Aria Icons combines a web catalog of about 1.4 million open-source SVG icons, a command line tool and an MCP server. An AI agent can search collections, fetch one icon or a batch, find similar icons across sets, and map existing imports onto a single collection.
Aria Icons is a monorepo with a website, a CLI published as the aria-icons package and an MCP server. The catalog mixes vendored sets such as Lucide, Tabler and Heroicons with Iconify collections and a large set of brand logos.
Icon ids follow a collection:name pattern, for example lucide:house or thesvg:github. The same ids work in the CLI, the REST endpoints and the MCP tools, which keeps an agent's requests short.
What changes in your agent's output
- Icons are written as files in the repository by the add command, instead of inline SVG pasted into chat.
- A doctor command audits a codebase that mixes several icon libraries.
- A migrate command maps existing icon-package imports onto one chosen collection.
- A suggest command recommends a consistent set for a source folder.
Local or hosted MCP
The local route runs aria-icons over stdio through npx. The README also lists a hosted HTTP endpoint with the same catalog, which suits clients that prefer a URL entry over a local process.
Who Aria Icons is for
Best for
- Teams cleaning up a codebase that imports from three icon packages and want one consistent set.
- Developers who need brand logos and general icons from a single search.
- Agents working beside shadcn MCP components that need matching icons.
Not for
- Projects with strict license rules and no time to check sets. The README says icons keep their own upstream licenses, including copyleft ones.
- Custom illustration work. It finds existing icons only.
- Anyone who wants a zero-network setup, because the CLI and hosted MCP call a public API. Keyline Icons MCP is another option to compare.
Use it with UiChemy
Aria Icons covers icons inside code. For a WordPress build, UiChemy converts a Figma design with Figma to WordPress and lets you refine it with Composer in Elementor or Gutenberg. Click Get Started on uichemy.com.
Connect Aria Icons MCP: 1.4M SVG Icons and a CLI for AI Coding Agents to your AI client
npx -y aria-icons@latest setupRun setup
Execute
npx -y aria-icons@latest setup, or use bunx. The README says it configures MCP for Cursor, Claude, VS Code and others.Or edit config
Paste the stdio entry above into your client's MCP settings. Running
aria-iconswith no arguments also starts the stdio server.Hosted option
Use the URL entry
https://icons.leularia.com/api/mcpfor the same catalog without a local process.Try the CLI
Run
search house, thenget lucide:house, thenaddwith icon names to write files into the repo.Audit your project
Run
doctorto see mixed libraries, thensuggest src/for a recommended consistent set.
Client configuration
{
"mcpServers": {
"aria-icons": {
"command": "npx",
"args": ["-y", "aria-icons"]
}
}
}Endpoints and ports
npx -y aria-iconsstdiohttps://icons.leularia.com/api/mcpSame catalog, hosted with the websiteGET /api/v1/search?q=Also icon, icons, collections, similar and equivalent endpointsWhat you can do with it
- Large catalogAbout 1.4 million icons, with more than 200 Iconify sets and over 6,500 brand logos.
- Write-as-sourceThe add command puts icon files in your repo, so nothing depends on a runtime fetch.
- Cross-set mappingEquivalent and similar endpoints translate an icon between collections.
- Library auditDoctor shows where a project mixes several icon packages.
- Migration commandRewrite imports to a single collection through the migrate command.
- Two MCP transportsStdio for local clients and a hosted HTTP endpoint with the same catalog.
- Public REST APISearch, single and batch icon lookups, collections and similar icons are available over HTTP.
- Project configAn init command writes
.aria-icons.jsonfor project settings.
Tools it exposes
search
Searches every collection in the catalog, by query.
get
Prints the SVG or framework source for one icon id.
add
Writes icon files into the repo.
similar
Finds similar icons, including icons from other sets.
equivalent
Maps an icon to its counterpart in another collection.
migrate
Maps existing icon-package imports onto one collection (CLI command).
doctor
Audits a codebase for mixed icon libraries (CLI command).
suggest
Recommends a consistent set for a source folder (CLI command).
Frequently asked questions
What is Aria Icons?
It is an open-source icon catalog with a CLI and an MCP server. The README describes about 1.4 million searchable SVG icons, and an agent can search, fetch and write icons into a repository through the commands or the MCP tools.
How do I install Aria Icons MCP?
Run npx -y aria-icons@latest setup, which configures the server for the supported agents. You can also add the stdio entry with npx -y aria-icons by hand, or use the hosted HTTP endpoint from the README.
Is it free to use?
The code is MIT licensed. The icons come from many upstream sets and keep their own licenses, which include MIT, Apache-2.0, ISC and CC0 as well as copyleft terms. Check the set license before you ship.
What does the doctor command do?
It audits a project that uses more than one icon library. Pair it with suggest to see a recommended single set, then run migrate to map existing imports onto that collection.
Can it find the same icon in another library?
Yes. The similar and equivalent endpoints find alternatives or the matching icon in another set, which helps when you switch libraries. For a comparison with another icon server, see Unicon MCP.
Does the MCP server need a network connection?
The README says the CLI uses tiny payloads from a public API and has no icon database in the package, so search needs network access. Hosted MCP runs on the project website.
Where do the brand logos come from?
The README says brand logos come from theSVG, with more than 6,500 brands and variants, and Iconify supplies over 200 further sets. Contributions go through a pull request with a license for each set.


