# RemixIcon MCP
  
English | [简体中文](README.zh-CN.md)
A lightweight [Model Context Protocol](https://modelcontextprotocol.io/) (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
```bash
# 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:
```bash
# 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`
```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)**
```bash
# 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**
```bash
# Quick command-line setup
claude mcp add --transport stdio remixicon -- npx -y remixicon-mcp
```
Or manually add to your project's `.claude/settings.json`:
```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**
```bash
# 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:**
```json
{
"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
```bash
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](LICENSE)
