Phosphor Icons MCP Server

A Model Context Protocol (MCP) server that provides access to Phosphor Icons - a flexible icon family with 6 different weights and over 1,000+ icons.

Important: This is a community-driven, AI-assisted MCP server and is not an official repository or affiliated with the Phosphor Icons project. This project was created with AI assistance and is maintained by the community. The original Phosphor Icons project can be found at https://github.com/phosphor-icons.

Features

• 🎨 6 Icon Weights: thin, light, regular, bold, fill, and duotone
• 🌈 Color Customization: Apply any color (hex, RGB, named colors, or currentColor)
• 📏 Size Control: Specify custom sizes in pixels
• 🔍 Search Icons: Find icons by name, category, or tags
• 📦 Batch Operations: Get multiple icons at once
• 📚 Catalog Access: Browse all available icons with metadata
• 🛠️ Implementation Guides: Get framework-specific integration help

Installation

npm install

CLI

The package ships a phosphor-icons CLI for exporting SVG/PNG assets without calling MCP.

For local development, build first and run the compiled CLI:

npm run build
node dist/cli.js icon heart --weight bold --color "#ef4444" --size 32 --out heart.svg
node dist/cli.js icon house user gear --format png --size 24 --dir ./icons
node dist/cli.js search arrow --limit 5
node dist/cli.js categories

After package installation, use the bin command:

phosphor-icons icon heart --size 16 --out heart.svg
phosphor-icons icon heart --format png --size 16 --out heart.png
phosphor-icons search arrow --limit 5
phosphor-icons categories

CLI commands:

• icon <name...>: Fetch one or more icons as SVG or PNG.
• search <query>: Search icon names plus bundled metadata.
• categories: List bundled categories and examples.
• skill path: Print the bundled Codex skill directory path.

Flags for icon:

• --weight, -w: thin, light, regular, bold, fill, or duotone.
• --color, -c: Any SVG color value, including currentColor.
• --size, -s: Pixel size for width and height.
• --format, -f: svg or png.
• --out, -o: Output file for a single icon.
• --dir, -d: Output directory for batch exports.

The CLI reads icons from the installed @phosphor-icons/core package first. This keeps icon export fast, deterministic, and offline after npm install. If local assets are unavailable, it falls back to the Phosphor Core GitHub raw URL.

CLI Smoke Test

npm install
npm run build
node dist/cli.js icon heart --size 16 --out live-heart.svg
node dist/cli.js icon heart --format png --size 16 --out live-heart.png
node dist/cli.js search arrow --limit 5

Expected:

• live-heart.svg contains width="16" height="16".
• live-heart.png is created with non-zero file size.
• Search returns arrow-related icon names.

Skills Extension

This package includes a Codex/Agents skill at skills/phosphor-icons/SKILL.md. After installing the package, locate it with:

phosphor-icons skill path

The skill gives agents concise rules for icon search, retrieval, export, and framework implementation. Use this path when registering the skill with an agent runtime or copying the skill into an agent skills directory.

Vercel Skills CLI Compatibility

The repository is compatible with the Vercel Labs skills CLI format: skills live under skills/<name>/SKILL.md and the file starts with name and description YAML frontmatter.

List skills from this repository:

npm run skills:list
# or
npx skills add . --list

Install the bundled skill from a local checkout:

npx skills add . --skill phosphor-icons --agent codex --copy -y

Install from GitHub after publishing:

npx skills add lasaths/phosphor-icons-mcp --skill phosphor-icons --agent codex -y

Install from an npm package checkout by resolving the skill path:

phosphor-icons skill path
npx skills add ./skills/phosphor-icons --agent codex --copy -y

Development

Run the development server:

npm run dev

This will start the server on port 8081 and open the Smithery playground for testing.

Configuration

The server supports an optional configuration parameter:

• defaultWeight: Set the default icon weight (thin, light, regular, bold, fill, duotone). Default: regular

Tools

get-icon

Retrieve one or more SVG icons from Phosphor Icons library. Provide either a single icon name or an array of names for batch retrieval.

Parameters:

• name (string, optional): Single icon name in kebab-case (e.g., 'arrow-left', 'user'). Use this for a single icon.
• names (array, optional): Array of icon names for batch retrieval. Use this for multiple icons.
• weight (optional): Icon weight/style
• color (optional): Icon color - accepts hex (#FF0000), RGB (rgb(255,0,0)), named colors (red), or 'currentColor'
• size (optional): Icon size in pixels (sets both width and height)
• format (optional): Output format (svg or png). Default: svg
• saveToFile (optional): Path to save the PNG file (single icon only)
• saveDir (optional): Directory to save PNG files (multiple icons only)

Examples:

get-icon name="heart" weight="bold" color="#FF0000"
get-icon names=["star", "heart"] weight="fill" color="gold" size=48
get-icon name="user" color="currentColor"

search-icons

Search for icons by name, category, or tags.

Parameters:

• query (string): Search term
• limit (optional): Maximum results to return (default: 10)

Example:

search-icons query="arrow" limit=5

list-categories

Get a list of all available icon categories.

Resources

phosphor://catalog

Complete catalog of popular Phosphor Icons with metadata including categories, tags, and available weights.

phosphor://weights

Detailed information about the 6 available icon weights/styles and their best use cases.

Prompts

implement-icon

Get guidance on implementing a Phosphor icon in your project.

Parameters:

• iconName (string): Name of the icon
• framework (string): Frontend framework (html, react, vue, svelte, angular)

Publishing to Smithery

1. Push your code to GitHub
2. Visit smithery.ai/new
3. Connect your GitHub repository
4. Configure automatic deployments

Icon Weights

• Thin: Delicate, minimal strokes - best for large sizes
• Light: Subtle, refined appearance - modern designs
• Regular: Balanced, versatile - general use (default)
• Bold: Strong, impactful - emphasis and small sizes
• Fill: Solid, filled shapes - strong emphasis
• Duotone: Two-tone design - visual interest

Examples

Get a red heart icon in bold:

// Returns SVG content for a bold red heart icon
get-icon({ name: "heart", weight: "bold", color: "#FF0000" })

Get a blue star icon at custom size:

// Returns a 48px blue filled star icon
get-icon({ name: "star", weight: "fill", color: "#3B82F6", size: 48 })

Search for navigation icons:

// Returns list of icons related to navigation
search-icons({ query: "navigation", limit: 10 })

Get multiple colored icons for a UI:

// Get home, user, and settings icons all in blue
get-icon({ 
  names: ["home", "user", "gear"],
  weight: "regular",
  color: "#3B82F6",
  size: 24
})

Disclaimer

NO WARRANTY OR LIABILITY

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

USE AT YOUR OWN RISK

• This is an unofficial, community-driven project created with AI assistance
• The software is provided without any guarantees or support
• Users are responsible for testing and validating the software for their use cases
• The maintainers are not responsible for any damages, data loss, or issues arising from the use of this software
• This project is not endorsed by or affiliated with the official Phosphor Icons project

License

This MCP server is MIT licensed. Phosphor Icons are also MIT licensed.

Links

• 🌐 Phosphor Icons Website
• 💻 Original Phosphor Icons Repository (Official)
• 📦 Phosphor Icons Core
• 📖 Smithery Documentation
• 🔧 MCP Protocol

Credits

• Icons: Provided by Phosphor Icons - created by Tobias Fried
• MCP Server: Community-driven project created with AI assistance
• Maintainers: Community contributors (not affiliated with Phosphor Icons)