fontawesome-mcp

chrisreedio/fontawesome-mcp

3.2

If you are the rightful owner of fontawesome-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Font Awesome Pro MCP Server is a Node.js-based server that provides fuzzy search and retrieval functionality for Font Awesome Pro icons, utilizing the Model Context Protocol (MCP) for enhanced client-server interactions.

Tools
2
Resources
0
Prompts
0

๐ŸŽฏ Font Awesome Pro MCP Server

A Model Context Protocol (MCP) server that provides fuzzy search and retrieval functionality for Font Awesome Pro icons. Built with Node.js, TypeScript, and Express.

โœจ Features

  • ๐Ÿ” Fuzzy Search: Find icons using intelligent search with Fuse.js
  • ๐Ÿ“ฆ Icon Retrieval: Get complete icon data including SVG content
  • ๐Ÿ”Œ MCP Compatible: Standard JSON-RPC interface for MCP clients
  • ๐ŸŒ Multiple Access Methods: HTTP API, MCP protocol, and direct SVG endpoints
  • ๐Ÿ’Ž Font Awesome Pro Support: Access to all Pro icon styles (solid, regular, light, thin, duotone)

๐Ÿ“‹ Prerequisites

  • Node.js 18+
  • Font Awesome Pro license with NPM access token configured in ~/.npmrc:
    @fortawesome:registry=https://npm.fontawesome.com/
    //npm.fontawesome.com/:_authToken=YOUR_TOKEN_HERE
    

๐Ÿš€ Installation

Option 1: NPM Package (Coming Soon)

Once published to NPM, you can install directly:

# Install and run via npx (no local setup required)
npx @chrisreedio/fontawesome-pro-mcp

# Or install globally
npm install -g @chrisreedio/fontawesome-pro-mcp
fontawesome-pro-mcp

Option 2: Development/Local Setup

# Clone the repository
git clone https://github.com/chrisreedio/fontawesome-mcp.git
cd fontawesome-mcp

# Install dependencies (uses your FA Pro token automatically)
npm install

# Build the project
npm run build

๐Ÿงญ Using

Set up this MCP server in your favorite clients.

Claude Desktop

Recommended (npx):

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

Local development path:

{
  "mcpServers": {
    "fontawesome-pro": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/fontawesome-mcp/dist/mcp-server.js"]
    }
  }
}

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

Restart Claude Desktop after editing the config.

Cursor

Option 1: Easy Install - One-Click

Install MCP Server

or go to this deep link:

Option 2: Manual Setup

Steps:

  • Open Cursor Settings (Cmd+Shift+J) โ†’ MCP Servers
  • Add a server and paste one of the configs below
  • Restart Cursor if tools donโ€™t appear

Recommended (npx):

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

Local development path:

{
  "mcpServers": {
    "fontawesome-pro": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/fontawesome-mcp/dist/mcp-server.js"]
    }
  }
}

Tips:

  • If you use many MCP servers, ensure this one isnโ€™t disabled in Cursorโ€™s MCP UI
  • Some Cursor builds prioritize a limited number of tools; placing this server earlier can help

VS Code

You can use either the Claude Code CLI or the Claude Dev extension.

CLI (recommended):

claude mcp add fontawesome-pro -- npx -y @chrisreedio/fontawesome-pro-mcp

Local path alternative:

claude mcp add fontawesome-pro node /ABSOLUTE/PATH/TO/fontawesome-mcp/dist/mcp-server.js

Claude Dev (Cline) config example:

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

Common locations:

  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

๐ŸŽฎ Usage

Development

npm run dev

Production

npm start

The server runs on http://localhost:8000 by default. Set PORT environment variable to change.

๐Ÿ”— API Endpoints

โค๏ธ Health Check

GET /health

Returns server status and timestamp.

๐ŸŒ Simple HTTP API

๐Ÿ” Search Icons
POST /api/search
Content-Type: application/json

{
  "query": "home",
  "limit": 5,
  "style": "solid"  // optional: solid|regular|light|thin|duotone|brands
}
๐Ÿ“ฆ Get Specific Icon
POST /api/icon
Content-Type: application/json

{
  "name": "house-signal",
  "style": "solid"
}

๐Ÿ”Œ MCP JSON-RPC Protocol

๐Ÿ“‹ List Available Tools
POST /rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
โšก Call a Tool
POST /rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fuzzySearch",
    "arguments": {
      "query": "search",
      "limit": 3
    }
  }
}

๐ŸŽจ Direct SVG Access

GET /svg/:style/:name.svg

Example: http://localhost:8000/svg/solid/house-signal.svg

๐Ÿ› ๏ธ Available Tools

fuzzySearch

Search Font Awesome Pro icons using fuzzy matching.

Parameters:

  • query (string): Search query for icons
  • limit (number, optional): Maximum results to return (default: 20)
  • style (string, optional): Filter by icon style

Returns: Array of matching icons with metadata.

getIcon

Get a specific Font Awesome Pro icon with complete data including SVG content.

Parameters:

  • name (string): The icon name (e.g., "home", "user")
  • style (string): The icon style (solid|regular|light|thin|duotone|brands)

Returns: Icon object with SVG content.

๐Ÿ“„ Response Format

Icons are returned with the following structure:

{
  "name": "house-signal",
  "style": "solid", 
  "label": "House Signal",
  "search": {
    "terms": ["abode", "building", "connect", "family", "home", "residence", "smart home", "wifi", "www"]
  },
  "unicode": "e012",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 576 512\">...</svg>"
}

๐Ÿ—๏ธ Architecture

src/
โ”œโ”€โ”€ server.ts          # Express server + MCP setup
โ”œโ”€โ”€ fa/               # Font Awesome helpers
โ”‚   โ”œโ”€โ”€ types.ts      # TypeScript interfaces
โ”‚   โ””โ”€โ”€ loader.ts     # Metadata loading + SVG retrieval
โ””โ”€โ”€ methods/          # MCP method implementations
    โ”œโ”€โ”€ fuzzySearch.ts # Icon search functionality  
    โ””โ”€โ”€ getIcon.ts     # Icon retrieval functionality

๐Ÿšข Production Deployment

For production use, you'll want to run the server as a persistent service that automatically restarts on failure and survives system reboots. Here are the most common deployment approaches:

โšก PM2 Process Manager (Recommended)

PM2 is a popular Node.js process manager that handles automatic restarts, logging, and clustering.

# Install PM2 globally
npm install -g pm2

# Start the server
pm2 start npm --name "fontawesome-mcp" -- start

# Save current PM2 processes
pm2 save

# Setup auto-restart on system reboot
pm2 startup

# Monitor the process
pm2 status
pm2 logs fontawesome-mcp

๐Ÿณ Docker

Containerized deployment for consistent environments and easy scaling.

First, create a Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source and build
COPY . .
RUN npm run build

# Expose port
EXPOSE 8000

# Start server
CMD ["npm", "start"]

Then build and run:

# Build image
docker build -t fontawesome-mcp .

# Run container
docker run -d -p 8000:8000 --restart unless-stopped --name fontawesome-mcp fontawesome-mcp

# View logs
docker logs fontawesome-mcp

๐Ÿง systemd Service (Linux)

For Linux servers, systemd provides robust service management.

Create /etc/systemd/system/fontawesome-mcp.service:

[Unit]
Description=Font Awesome MCP Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/fontawesome-mcp
ExecStart=/usr/bin/node dist/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=8000

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable fontawesome-mcp
sudo systemctl start fontawesome-mcp

# Check status
sudo systemctl status fontawesome-mcp

๐Ÿ”ง Environment Variables

Set these environment variables for production:

NODE_ENV=production
PORT=8000
LOG_LEVEL=info

๐Ÿ› ๏ธ Development

Scripts

  • npm run dev - Development server with hot reload
  • npm run dev:mcp - Start local MCP server in development mode
  • npm run build - Build TypeScript to JavaScript
  • npm run start - Run production server
  • npm run start:mcp - Run local MCP server from built files
  • npm run clean - Remove build artifacts

Testing

Run the comprehensive test suite to verify functionality:

# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

The test suite includes:

  • Unit Tests: Core search and icon retrieval methods
  • Integration Tests: Local MCP server functionality via stdio
  • HTTP API Tests: All REST endpoints and MCP JSON-RPC interface
  • Error Handling: Validation and edge case scenarios

Tests verify both the HTTP server and local MCP server implementations work correctly.

Publishing

To publish this package to NPM:

# Ensure you're logged into NPM
npm login

# Publish the scoped package as public (required for @username/package-name format)
npm publish --access public

Note: This package uses a scoped name (@chrisreedio/fontawesome-pro-mcp), so the --access public flag is required to make it publicly accessible. Without this flag, NPM would try to publish it as a private package.

The package includes a prepublishOnly script that automatically builds the project before publishing.

Key Dependencies

  • Express: HTTP server framework
  • Fuse.js: Fuzzy search implementation
  • js-yaml: YAML parsing for FA metadata
  • zod: Schema validation
  • @modelcontextprotocol/sdk: MCP protocol support

๐Ÿ“„ License

MIT

๐Ÿ’Ž Font Awesome Pro

This project requires Font Awesome Pro. Font Awesome Pro is a commercial product - ensure you have appropriate licensing for your use case.