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

Usage

As a Standalone CLI Tool

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

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

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)

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

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

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

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:

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

Project Structure

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

License

MIT License