An MCP server that provides Heroicons as SVG.

This server lets MCP clients (for example Claude , Cline, or Codex) easily:

• list icons by style,
• search icons by name or keywords,
• retrieve the full SVG source of a specific icon.

• Uses Heroicons 2.x from the heroicons npm package.
• Supported styles:
  • outline (24x24)
  • solid (24x24)
  • mini (20x20)
  • micro (16x16)
• Built-in caching for faster performance:
  • icon name cache,
  • icon file path cache,
  • SVG content cache.
• Verbose error messages when input is invalid or an icon cannot be resolved.
• Covered by tests (vitest).

• Node.js 18+
• npm

The server uses stdio MCP transport, so your MCP client should launch it with:

npx -y heroicons-svg-mcp@latest

Add this to your Claude Code MCP config:

{
  "mcpServers": {
    "heroicons-svg": {
      "command": "npx",
      "args": ["-y", "heroicons-svg-mcp@latest"]
    }
  }
}

Add this to your Cursor MCP config (for example .cursor/mcp.json):

{
  "mcpServers": {
    "heroicons-svg": {
      "command": "npx",
      "args": ["-y", "heroicons-svg-mcp@latest"]
    }
  }
}

Codex-style TOML example:

[mcp_servers.heroicons-svg]
command = "npx"
args = ["-y", "heroicons-svg-mcp@latest"]

Description: lists all available Heroicons, optionally filtered by style.

Input:

• style (optional): outline | solid | mini | micro

Example input:

{
  "style": "outline"
}

Response:

• content[0].text: human-readable text output.
• structuredContent:
  • icons: { name, style }[]
  • iconsByStyle: icon names grouped by style
  • styles: included styles
  • total: total number of icon variants

Description: searches Heroicons by name or keywords, optionally filtered by style.

Input:

• query (required): search text
• style (optional): outline | solid | mini | micro

Example input:

{
  "query": "arrow right",
  "style": "mini"
}

Response:

• content[0].text: human-readable match list.
• structuredContent:
  • icons: { name, style, score }[] (ranked matches)
  • query: normalized search query
  • styles: included styles
  • total: total match count

Description: retrieves the full SVG source for an icon.

Input:

• name (required): icon name (for example academic-cap)
• style (required): outline | solid | mini | micro

Example input:

{
  "name": "academic-cap",
  "style": "outline"
}

Response:

• content[0].text: full valid SVG markup (<svg ...>...</svg>)
• structuredContent:
  • name
  • style
  • svg (same SVG source)

Run tests:

npm test

Run tests with coverage:

npm run test:coverage

Watch mode:

npm run test:watch

• index.js: CLI bootstrap entrypoint.
• src/server.js: MCP server creation and tool registration.
• src/icons.js: icon logic, search, retrieve, caching.
• tests/icons.unit.test.mjs: unit tests.
• tests/server.integration.test.mjs: MCP server integration tests.
• tests/index.bootstrap.test.mjs: CLI/bootstrap behavior tests.

Typical error cases:

• unsupported style value,
• missing or invalid name,
• icon not found in the specified style.

The server returns verbose, actionable errors so MCP clients can surface clear feedback.

Examples:

• Unsupported style "foo". Supported styles: outline, solid, mini, micro.
• Invalid icon name "...".
• Icon "academic-cap" not found in style "mini".

• Project: MIT
• Heroicons: MIT