RemixIcon MCP

English | 简体中文

A lightweight Model Context Protocol (MCP) server that maps icon-focused keywords directly to Remix Icon metadata. Provide concise keywords (up to 20), receive the top 5 matching icon names and metadata – clean architecture with FlexSearch-powered local search.

Features

• Smart Keyword Input – Supports up to 20 comma-separated keywords while rejecting natural-language sentences for optimal search quality.
• Fixed Top-5 Results – Returns exactly 5 most relevant icons for focused decision-making.
• FlexSearch-backed Index – Uses FlexSearch v0.8's document index for high-performance token lookup over the local Remix Icon catalog.
• Clean Architecture – Domain entities, application use cases, infrastructure adapters, and MCP interface remain isolated for easy testing.
• CLI Ready – Can be run as a standalone CLI tool via npx remixicon-mcp or integrated into MCP clients.
• LLM-ready Responses – Returns ranked candidates, matched tokens, and explicit guidance instructing the model to choose exactly one icon.

Quick Start

Installation

# Install as CLI tool globally
npm install -g remixicon-mcp

# Or run directly with npx
npx remixicon-mcp

# For development
pnpm install
pnpm typecheck
pnpm test

Usage

As a Standalone CLI Tool

You can run the MCP server directly via stdio for testing or integration:

# Run with npx
npx remixicon-mcp

# Or if installed globally
remixicon-mcp

Platform Setup

Claude Desktop

Configuration
Add the following to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "remix-icon": {
      "command": "npx",
      "args": ["-y", "remixicon-mcp"]
    }
  }
}

Setup Steps

1. Save the configuration file
2. Completely quit and restart Claude Desktop
3. The search_icons tool will be available in your conversations

Claude Code

Option 1: Marketplace Plugin (Recommended)

# In Claude Code, add the marketplace plugin
/plugin marketplace add Remix-Design/remixicon-mcp

Benefits:

• Automatic installation and updates
• Complete plugin metadata and versioning
• Rich discovery with keywords and categorization
• Full integration with Claude Code's plugin ecosystem

Option 2: Manual Configuration

# Quick command-line setup
claude mcp add --transport stdio remixicon -- npx -y remixicon-mcp

Or manually add to your project's .claude/settings.json:

{
  "mcp": {
    "servers": {
      "remix-icon": {
        "command": "npx",
        "args": ["-y", "remixicon-mcp"]
      }
    }
  }
}

Setup Steps

1. Choose one of the installation methods above
2. Restart Claude Code for the changes to take effect
3. The search_icons tool will be available in your sessions

Codex

Configuration

# Quick command-line setup
codex mcp add remixicon -- npx -y remixicon-mcp

Setup Steps

1. Run the installation command above
2. Restart Codex for the changes to take effect
3. The search_icons tool will be available in your conversations

Available Tools

The server communicates over stdio using JSON-RPC 2.0 via the official @modelcontextprotocol/sdk and exposes a single tool:

search_icons

Input: keywords string (comma-separated, up to 20 keywords)
Output: Top 5 most relevant icons with metadata
Format: Human-readable summary + structured metadata

Example Usage

JSON-RPC Call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_icons",
    "arguments": {
      "keywords": "layout, grid, design"
    }
  }
}

Sample Response:
The server returns the top 5 icons that match your keywords, complete with names, categories, and usage information.

Project Structure

.
├── bin/
│   └── run.cjs                     # CLI entry point for npx execution
├── src/
│   ├── cli/                        # CLI runner implementation
│   ├── bootstrap/                  # Dependency wiring for Clean Architecture boundaries
│   ├── domain/                     # Icon entities and keyword parser
│   ├── application/                # Search use case orchestrating validation and ranking
│   ├── infrastructure/search/      # FlexSearch-backed repository implementation
│   ├── interface/mcp/              # MCP server built with @modelcontextprotocol/sdk
│   └── data/tags.json              # Remix Icon tags for search functionality
├── tests/                          # Vitest suites covering parser and use case behaviour
├── .claude-plugin/
│   └── marketplace.json            # Marketplace metadata for Claude Code plugin discovery
├── package.json                    # pnpm-friendly manifest and scripts
└── tsconfig.json                   # Strict TypeScript configuration with Node typings

Implementation Notes

• Keywords are parsed with Unicode-aware boundaries, supporting up to 20 comma-separated keywords while rejecting sentence-style inputs.
• Enhanced detection differentiates between keyword lists (with delimiters) and natural language sentences (space-separated phrases).
• FlexSearch indexes icon names, tags, usage, and categories; field weights plus token matches drive deterministic scores.
• Fixed top-5 results provide focused, relevant matches without configuration complexity.
• The application layer combines parser validation, repository queries, and response formatting so the interface only handles transport concerns.
• MCP responses include natural-language guidance and machine-readable matches so LLM clients can choose exactly one icon.
• CLI runner enables standalone execution via npx or global installation for easy integration.

Development Scripts

pnpm typecheck   # Strict TypeScript check (tsc --noEmit)
pnpm test        # Run Vitest suites
pnpm exec biome check --write --unsafe   # Format + fix code with Biome

License

MIT License

{
  "name": "remix-icon-mcp",
  "owner": {
    "name": "Remix-Design",
    "url": "https://github.com/Remix-Design"
  },
  "metadata": {
    "description": "Official Remix Icon MCP server providing intelligent icon search and discovery with semantic matching",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "remix-icon-mcp",
      "source": "./",
      "description": "A Model Context Protocol server for Remix Icon search with FlexSearch-powered semantic matching. Maps icon-focused keywords to Remix Icon metadata, providing top 5 most relevant icons with clean architecture and local search.",
      "version": "1.0.0",
      "author": {
        "name": "Remix-Design",
        "url": "https://github.com/Remix-Design"
      },
      "homepage": "https://github.com/Remix-Design/RemixIcon-MCP",
      "repository": "https://github.com/Remix-Design/RemixIcon-MCP",
      "license": "MIT",
      "keywords": [
        "mcp",
        "remix-icon",
        "icons",
        "search",
        "design",
        "ui",
        "flexsearch",
        "semantic-search",
        "icon-search"
      ],
      "category": "productivity",
      "strict": false,
      "mcpServers": {
        "remix-icon": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "remixicon-mcp"
          ]
        }
      }
    }
  ]
}