io.github.curlymolelabs/supericons

Official4 tools

by curlymolelabs

Supericons

Semantic SVG icon search and recommendations for AI coding agents.

Searches and recommends semantic SVG icons for AI coding agents.

Topics

claude-codecodexcodingcoding-agentcoding-agentscursoriconslucidelucide-iconsmcpsemantic-searchsvgtablertabler-icons

Captured live from the server via tools/list.

search_icons

Search 20,000+ curated SVG icons across 11 libraries by meaning, label, visual description, tags, and synonyms. Use this when the user describes an icon concept such as "database", "user profile", "chill", "security", "AI model", or "OpenAI Codex logo". Returns matching icons with SVG code and public semantic guidance.

Parameters (5)

querystringrequired
Icon concept or search phrase, for example "database", "user profile", "chill", "trash", "upload cloud", "AI model", or "beautiful".
librarystring
Optional library key. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute.
stylestring
Optional style preference. Use "any" unless the user asks for outline or solid icons.
localestring
Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th.
limitnumber
Maximum number of icons to return. Use 5-10 for browsing and 1-3 for quick agent choices.

recommend_icons

Recommend a coherent icon set for named UI slots in a product, app, dashboard, or navigation flow. Use this when the user needs several icons that should work together. Returns one recommendation and optional alternatives for each slot.

Parameters (7)

taskstringrequired
Overall UI task, for example "choose icons for an AI dashboard sidebar" or "select bottom navigation icons for a finance app".
slotsarrayrequired
List of UI slots to fill, for example ["model", "prompt", "dataset", "evaluation"].
librarystring
Optional library key when the user wants a consistent icon family. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute.
stylestring
Optional style preference. Use "outline" for most sidebar and toolbar icon sets unless the user asks otherwise.
localestring
Optional locale for multilingual slot labels. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th.
limit_per_slotnumber
Number of choices to return for each slot. Use 1 for a final pick or 2-3 when the user wants alternatives.
response_modestring
Response size mode. Use plan for compact icon IDs and reasons, assets to include SVG only for each top recommendation, or full to include SVG and semantic payloads for all returned choices.

get_icon

Retrieve one exact SVG icon when the icon ID and library are already known. Use search_icons first if the user only described a concept. Returns SVG code and public semantic guidance for the exact icon.

Parameters (3)

idstringrequired
Exact icon ID without the library prefix, for example "database", "user-circle", "brain-circuit", or "arrow-down".
librarystringrequired
Required library key for the exact icon. Supported values include si, lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons, and mingcute.
stylestring
Optional style preference. Use "any" unless the caller needs a specific variant.

list_libraries

List the free icon libraries available through the hosted Supericons MCP server. Use this before filtering by library or when a user asks which icon libraries are supported.

No parameters.

README.md3 KBView on GitHub

Supericons

Semantic SVG icon search for AI coding agents.

Supericons helps agents find icons by meaning, not only by file name. Use it to search 20,000+ free icons, retrieve SVG code, and recommend icon sets for app navigation, dashboards, tools, and product UI.

Current Package

Use the scoped npm package:

text

@supericons/mcp

Latest verified package version: 0.4.9.

New installs should use the scoped package above.

Quick Install

Use this config in any MCP-capable coding agent:

json

{
  "mcpServers": {
    "supericons": {
      "command": "npx",
      "args": ["-y", "@supericons/mcp"]
    }
  }
}

Codex Plugin Setup

Supericons also includes a Codex plugin manifest.

If you are testing from this public GitHub repo, add this marketplace file to Codex:

text

.agents/plugins/marketplace.json

Then restart Codex and install Supericons from the plugin list.

The Codex plugin uses:

text

.codex-plugin/plugin.json
.codex-mcp.json
skills/supericons-icon-search/SKILL.md

Codex Manual MCP Setup

If you only want MCP without the plugin wrapper, use these fields in Codex:

text

Name: supericons
Transport: stdio
Command to launch: npx
Arguments:
-y
@supericons/mcp

IDE Setup Fields

If your IDE shows a form instead of a JSON file, enter:

text

Name: supericons
Transport: stdio
Command: npx
Arguments:
-y
@supericons/mcp

If your IDE has one argument field, enter:

text

-y @supericons/mcp

Leave environment variables empty for free icon search.

Pro Setup

For premium icons or Pro tools, add this environment variable:

text

SUPERICONS_API_KEY=your_api_key_here

Do not paste API keys into public issues, screenshots, or shared config files.

Hosted MCP Endpoint

MCP setup page:

text

https://supericons.dev/mcp/

Hosted endpoint:

text

https://mcp.supericons.dev/mcp

Server card:

text

https://mcp.supericons.dev/.well-known/mcp/server-card.json

Available Tools

search_icons : Search free icon libraries by meaning, label, visual description, tags, and synonyms.

recommend_icons : Recommend icons for UI slots such as dashboard navigation, app tabs, settings panels, or product features.

get_icon : Retrieve one SVG icon by icon ID and library.

list_libraries : List the free icon libraries available through Supericons MCP.

Example Prompts

text

Use Supericons MCP to find a database icon. Prefer Lucide outline icons and show the icon id, library, and SVG.

text

Use Supericons MCP to recommend icons for an AI dashboard sidebar. The slots are model, prompt, dataset, evaluation, deployment, and monitoring. Prefer Lucide outline icons.

Public Repo Scope

This repository is only a lightweight setup wrapper for agent directories and IDE users. It does not include the private Supericons website source, the full semantic registry, internal build workflows, private data, service keys, or premium icon assets.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "supericons": {
      "command": "npx",
      "args": [
        "-y",
        "supericons-mcp@0.4.1"
      ]
    }
  }
}

Topics

search_icons

recommend_icons

get_icon

list_libraries

Supericons

Current Package

Quick Install

Codex Plugin Setup

Codex Manual MCP Setup

IDE Setup Fields

Pro Setup

Hosted MCP Endpoint

Available Tools

Example Prompts

Links

Public Repo Scope

Install