# Supericons [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/curlymolelabs/supericons  
**GitHub Stars:** 2  
**npm Downloads (last month):** 4505  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/supericons

## Description
Multilingual semantic SVG icon search with previews for AI coding agents. 20,000+ icons.

## Tools
Capabilities this server exposes over MCP:

- **search_icons** — Use this as the main icon tool. Search 20,000+ curated SVG icons across 11 libraries using synonym expansion. When matches exist, the response includes a paste-ready suggested answer, a direct preview image, and Markdown that can show the image in the final reply. When no supported match exists, it returns an honest structured no-result with a next step and no fabricated icon. Omit library to search all libraries. If you choose a library yourself, use prefer. Use strict only when the user explicitly requires that library. Library key si means Supericons, not Simple Icons. Pro API keys unlock workflow tools; premium pack icon search is not exposed through MCP yet.
- **recommend_icons** — Recommend the most suitable icons for up to 20 UI slots in one call. Uses task context to narrow ambiguous meanings. When context is insufficient, returns needs_clarification with labeled interpretation options instead of guessing. Invalid inputs and service failures return a plain-language reason and a next step instead of a bare protocol error. Returns shortlist choices with preview-ready SVGs, explicit public library labels, browser preview URLs, short reasons, and SI semantic guidance when available. Library key si means Supericons, not Simple Icons.
- **get_icon** — Retrieve a specific free icon by its ID and library. Returns the full SVG code, metadata, explicit public library labels, browser preview URL, and SI semantic guidance when available. Premium pack icon retrieval is not exposed through MCP yet.
- **preview_icons** — Refine an icon result set or preview known icon refs returned by another Supericons tool. Use search_icons first for normal icon requests. Long icon lists are accepted and safely truncated to 12. Returns ready-to-use Markdown, a browser preview fallback, a direct PNG image URL, and, when requested, an MCP image contact sheet.
- **list_libraries** — List the free icon libraries available through Supericons MCP with their names, icon counts, and descriptions.
- **list_motion_presets** — List the Motion Lab presets currently available through Supericons MCP, including preset id, label, group, description, and supported triggers. Motion Lab MCP is a Pro workflow tool.
- **get_motion_recipe** — Return a human-readable Motion Lab recipe for a preset, trigger, and duration. Use this before export tools when you want to compare presets or confirm the motion fit. Motion Lab MCP is a Pro workflow tool.
- **export_motion_css** — Generate Motion Lab CSS for a Supericons icon. The returned CSS uses a portable {{ICON_SELECTOR}} token you replace with your inline SVG selector. Call get_motion_recipe first if you want to compare presets before exporting. Motion Lab MCP is a Pro workflow tool.
- **export_animated_svg** — Generate a self-contained animated SVG using Motion Lab presets. Call get_motion_recipe first if you want to compare presets before exporting. Motion Lab MCP is a Pro workflow tool.
- **animate_icon** — Generate both Motion Lab CSS and a self-contained animated SVG for one icon. The CSS output uses a portable {{ICON_SELECTOR}} token you replace with your inline SVG selector. Call get_motion_recipe first if you want to compare presets before exporting. Motion Lab MCP is a Pro workflow tool.
- **inspect_converter_options** — List the current Converter MCP options, workflow hints, and recommended starting combinations. Converter MCP is a Pro workflow tool.
- **inspect_converter_input** — Inspect a PNG before tracing. Returns structural hints, likely risks, and recommended starting settings for Converter MCP.
- **convert_svg_to_png** — Convert an SVG string to PNG. Converter MCP is a Pro workflow tool.
- **convert_png_to_svg** — Convert a PNG payload to SVG. Converter MCP is a Pro workflow tool.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "supericons": {
    "command": "npx",
    "args": ["-y","@supericons/mcp@latest"],
    "env": {
      "SUPERICONS_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `SUPERICONS_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Supericons MCP server does

The Supericons MCP server connects AI coding agents to a searchable collection of more than 20,000 free SVG icons from 11 libraries. Its search is semantic rather than limited to exact filenames, so an agent can look for an icon using a meaning, label, visual description, tag, synonym, or supported multilingual term.

The server supports both individual icon lookup and broader UI planning. An agent can retrieve SVG code for a known icon, ask for recommendations across up to 20 named UI slots, or generate a visual comparison of candidate icons. This makes it suitable for interface work where the agent needs to select an icon family, inspect alternatives, or return implementation-ready SVG data.

## How it works

Supericons MCP server can be reached through the hosted streamable MCP endpoint at `https://mcp.supericons.dev/mcp`, or launched locally through the npm package `@supericons/mcp`. Hosted access is configured as a remote MCP server, while local access uses the `npx` command and standard input/output transport.

The free tools do not require an API key. Pro access uses the `SUPERICONS_API_KEY` environment variable. The repository separates the product plugin version from the MCP runtime version; the documented plugin release is `2.0.0`, while the npm and hosted runtimes are listed as `0.4.22`.

## Setup and configuration

For a local client configuration, register a server named `supericons` with `npx` as the command and these arguments:

- `-y`
- `@supericons/mcp@latest`

Clients that accept a single argument field can use `-y @supericons/mcp@latest`. Clients with remote MCP support can use the hosted endpoint instead. The repository includes public plugin manifests for Codex and Claude Code, along with an agent marketplace manifest and Codex-specific MCP and skill files.

For paid functionality, set `SUPERICONS_API_KEY` in the server environment. Do not place the key in committed configuration, public issues, screenshots, or shared chats.

## Tools and capabilities

The Supericons MCP server exposes these documented tools:

- `search_icons` searches icon content by meaning, metadata, visual description, and supported multilingual terms.
- `recommend_icons` proposes a consistent icon set for as many as 20 named interface slots.
- `get_icon` returns one exact SVG when both its icon ID and library are known.
- `preview_icons` creates a hosted preview page or image for comparing search results or known icon references.
- `list_libraries` returns the 11 free icon libraries available through the hosted server.

Search results can be used to request an icon ID, library, and SVG. Recommendation prompts can specify a UI context and a preferred library or style, such as Lucide outline icons.

## Limitations and notes

Exact icon retrieval requires the icon ID and library. Recommendations are limited to 20 named UI slots per request.

The repository is a public setup and directory wrapper rather than the private product implementation. It contains manifests, installation examples, support information, and brand assets; private product code, credentials, customer data, and internal operating data are excluded. The documented runtime package is `@supericons/mcp@0.4.22`; the README specifically notes that `@supericons/mcp@2.0.0` is not an npm package.

_Full upstream README: https://allmcps.com/mcp/supericons/readme_