Skip to main content
Glama

heroicons-mcp

Ask DeepWiki

A Model Context Protocol (MCP) server exposing Heroicons as resources and tools for LLMs and agentic applications. Built with Bun and the MCP TypeScript SDK.

What is Heroicons?

Heroicons is a popular library of hand-crafted SVG icons, designed by the makers of Tailwind CSS. The icons are available in multiple styles (Outline, Solid) and are easy to integrate into web projects.

Related MCP server: SupaUI MCP Server

What is MCP?

The Model Context Protocol (MCP) is a standard for AI tools to request specific context from sources outside their main training data.

This MCP server allows AI coding assistants and other agentic applications to access information about Heroicons, enabling better assistance and icon search capabilities.

Features

  • Exposes Heroicons as MCP resources (Outline and Solid styles)

  • Provides tools for searching icons by name or keywords

  • Allows listing all icons or icons within a specific style

  • Ready for integration with Claude Desktop and other MCP clients

  • Can be run as an HTTP server or a stdio-based MCP server

Prerequisites

Getting Started (Development)

1. Clone the repository

git clone https://github.com/SeeYangZhi/heroicons-mcp.git
cd heroicons-mcp

2. Install Bun (if you don't have it)

Refer to the official Bun installation guide.
After installation, restart your terminal and check:

bun --version

3. Install dependencies

bun install

4. Build the project

This compiles the TypeScript source to JavaScript in the build directory.

bun run build

Usage

HTTP Mode

You can run the HTTP server using npx:

npx heroicons-mcp

This starts the HTTP server (defaults to port 3000, as defined in src/http.ts).

Or install globally:

npm install -g heroicons-mcp

Then run:

heroicons-mcp

Stdio Mode

npx heroicons-mcp --stdio
# or if installed globally
heroicons-mcp --stdio

Local Development

There are two main ways to run the MCP server:

1. HTTP Mode

Suitable for clients that support communication over HTTP.

For development (using Bun):

bun run start
# or directly
bun run src/entry.ts

This runs the server defined in src/entry.ts, which defaults to HTTP mode.

2. Stdio Mode

Often used for direct integration with tools like Claude Desktop or the MCP Inspector, communicating over standard input/output.

For development (using Bun):

bun run src/entry.ts --stdio

Configuration with AI Tools

Example: Claude Desktop

To use this MCP server in Claude Desktop:

  1. Open your Claude Desktop configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

(Or use your preferred editor) 2. Add the server to the mcpServers section.

Option A: via npx:

{
  "mcpServers": {
    "heroicons": {
      "command": "npx",
      "args": ["heroicons-mcp", "--stdio"]
    }
  }
}

Option B: Pointing directly to the build output (ensure you have built the project using bun run build):

{
  "mcpServers": {
    "heroicons": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js", "--stdio"]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/heroicons-mcp/build/entry.js with the actual absolute path to your built entry.js file.

  1. Save the file and restart Claude Desktop.

  2. You should now see the "heroicons" server available in Claude's tools panel.

Note: The npx heroicons-mcp --stdio command is the recommended way for stdio mode.

Tools Available (MCP)

This MCP server exposes the following tools to AI coding assistants:

  1. list_all_icons

  • Description: Lists all available Heroicons, optionally filtered by style (outline, solid).

  • Parameters: style (optional: "outline" | "solid")

  1. search_icons

  • Description: Searches for Heroicons by name or keywords across all styles.

  • Parameters: query (string), style (optional: "outline" | "solid")

  1. get_icon_usage_examples

  • Description: Retrieves JSX example usage for a specific icon.

  • Parameters: name (string), style (string: "outline" | "solid")

Example Usage

Here's how an AI tool might use this MCP server:

  1. User asks AI tool: "Find me a 'user' icon from Heroicons, preferably the solid style."

  2. AI tool calls search_icons:

  • query: "user"

  • style: "solid"

  1. MCP server responds with a list of matching solid Heroicons (e.g., UserIcon, UserCircleIcon, UserPlusIcon).

  2. User asks tool: "Show usage example of UserIcon".

  3. AI tool calls get_icon_usage_examples:

  • name: "UserIcon"

  • style: "solid"

  1. MCP server responds with the JSX code example:

import { UserIcon } from "@heroicons/react/24/solid";

function Example() {
  return (
    <div>
      <UserIcon className="w-6 h-6 text-blue-500" />
    </div>
  );
}

Testing MCP Locally with Inspector

You can test the MCP server (stdio mode) locally using the MCP Inspector.

First, ensure the project is built:

bun run build

Then launch the Inspector and connect it to your server using the node ./build/entry.js command with the --stdio flag:

npx @modelcontextprotocol/inspector node ./build/entry.js --stdio

This will open the Inspector interface, allowing you to interactively test resources and tools exposed by your MCP server.

Development Scripts

  • bun run dev: Starts the server in HTTP mode for development (uses src/entry.ts).

  • bun run dev:stdio: Starts the stdio MCP server for development (uses src/entry.ts --stdio).

  • bun run build: Compiles TypeScript to JavaScript (output in build/).

  • bun run lint: Lints the codebase using ESLint.

Resources

License

MIT

Available Tools

3 tools
get_icon_usage_examplesB

Get usage examples for an icon

Inputs: name (required), style (required).

list_all_iconsB

List all icons from the heroicons library, optionally filtered by style

Inputs: style.

search_iconsB

Search for icons from heroicons by name or category

Inputs: query (required), category, limit, style.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing all icons, searching icons by criteria, and getting usage examples for a specific icon. There is no overlap in functionality, making it easy for an agent to select the right tool without confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_icon_usage_examples, list_all_icons, search_icons) with clear, descriptive verbs. The naming is uniform and predictable across the set.

    Tool Count5/5

    With 3 tools, this server is well-scoped for its purpose of accessing a heroicons library. Each tool serves a distinct and essential function, making the count appropriate without being too thin or heavy.

    Completeness5/5

    The tool set provides complete coverage for the domain: listing icons, searching icons, and getting usage examples. This covers the core workflows for accessing and utilizing an icon library, with no obvious gaps or dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      F
      maintenance
      MCP server for Hugeicons integration and documentation This is a TypeScript-based MCP server that provides tools and resources for integrating Hugeicons into various platforms. It implements a Model Context Protocol (MCP) server that helps AI assistants provide accurate guidance for using Hugeicons
      5
      26
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that allows FE/UI/Designers to retrieve SVG icons via the Iconify API by simply asking LLMs rather than manually searching websites.
      3
      21 npm
      4
      MIT