MIT License
This server provides access to the Heroicons library, enabling AI tools and applications to search, list, and retrieve usage examples for icons.
Search Icons: Search by name, category, or style (
solidoroutline) with optional result limitsList All Icons: Retrieve all icons, optionally filtered by style
Get Usage Examples: Fetch JSX usage examples for specific icons
Integration: Works with AI coding assistants for better icon-related suggestions
Multiple Modes: Supports HTTP or stdio-based communication for flexible integration
Provides JSX examples for using Heroicons in React applications, showing how to import and implement icons with styling.
Offers integration with Tailwind CSS styling in the icon usage examples, as Heroicons is designed by the makers of Tailwind CSS.
heroicons-mcp
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.
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:
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
{
"mcpServers": {
"heroicons": {
"command": "npx",
"args": ["heroicons-mcp", "--stdio"]
}
}
}
Option B: Pointing directly to the build output (ensure you have built the project using
{
"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.
Save the file and restart Claude Desktop.
You should now see the "heroicons" server available in Claude's tools panel.
Note: The
Tools Available (MCP)
This MCP server exposes the following tools to AI coding assistants:
list_all_icons
Description: Lists all available Heroicons, optionally filtered by style (outline, solid).
Parameters:
style(optional: "outline" | "solid")
search_icons
Description: Searches for Heroicons by name or keywords across all styles.
Parameters:
query(string),style(optional: "outline" | "solid")
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:
User asks AI tool: "Find me a 'user' icon from Heroicons, preferably the solid style."
AI tool calls :
query: "user"style: "solid"
MCP server responds with a list of matching solid Heroicons (e.g.,
UserIcon,UserCircleIcon,UserPlusIcon).User asks tool: "Show usage example of UserIcon".
AI tool calls :
name: "UserIcon"style: "solid"
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 (usessrc/entry.ts).bun run dev:stdio: Starts the stdio MCP server for development (usessrc/entry.ts --stdio).bun run build: Compiles TypeScript to JavaScript (output inbuild/).bun run lint: Lints the codebase using ESLint.
Resources
License
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
heroicons-mcp
Related MCP Servers
- MIT License
- MIT License