Remix Icon MCP

RemixIcon MCP

English | 简体中文

一款轻量级的 Model Context Protocol（MCP）服务，可将图标相关关键词直接映射到 Remix Icon 元数据。输入简洁的关键词（最多 20 个），即可获取匹配度最高的 5 个图标名称及元数据——采用整洁的架构，并通过 FlexSearch 实现本地搜索。

功能

• 智能关键词输入——支持输入最多 20 个以逗号分隔的关键词，同时拒绝自然语言句子，以确保最佳搜索质量。
• 固定返回前 5 个结果——准确返回最相关的 5 个图标，帮助聚焦决策。
• 由 FlexSearch 驱动的索引——使用 FlexSearch v0.8 的文档索引，对本地 Remix Icon 目录进行高性能词元查找。
• 整洁的架构——领域实体、应用用例、基础设施适配器和 MCP 接口彼此隔离，便于测试。
• 适用于 CLI——可通过 npx remixicon-mcp 作为独立 CLI 工具运行，也可集成到 MCP 客户端中。
• 适用于大模型的响应——返回经过排序的候选项、匹配的词元，以及明确指示模型恰好选择一个图标的说明。

快速开始

安装

# 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

使用方法

作为独立 CLI 工具使用

你可以直接通过 stdio 运行 MCP 服务，用于测试或集成：

# Run with npx
npx remixicon-mcp

# Or if installed globally
remixicon-mcp

平台配置

Claude Desktop

配置 将以下内容添加到你的 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"]
    }
  }
}

设置步骤

1. 保存配置文件
2. 完全退出并重启 Claude Desktop
3. search_icons 工具将在对话中可用

Claude Code

选项 1：Marketplace 插件（推荐）

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

优点：

• 自动安装和更新
• 完整的插件元数据和版本管理
• 通过关键词和分类轻松发现
• 与 Claude Code 的插件生态系统全面集成

选项 2：手动配置

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

或者，手动添加到项目的 .claude/settings.json：

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

设置步骤

1. 选择上述任一安装方式
2. 重启 Claude Code，使更改生效
3. search_icons 工具将在会话中可用

Codex

配置

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

设置步骤

1. 运行上述安装命令
2. 重启 Codex，使更改生效
3. search_icons 工具将在对话中可用

可用工具

该服务通过官方 @modelcontextprotocol/sdk 使用 JSON-RPC 2.0，通过 stdio 进行通信，并提供一个工具：

search_icons

输入：keywords 字符串（以逗号分隔，最多 20 个关键词）
输出：匹配度最高的 5 个图标及其元数据
格式：易读的摘要 + 结构化元数据

使用示例

JSON-RPC 调用：

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

响应示例： 服务会返回与你的关键词匹配度最高的 5 个图标，并提供名称、分类和用法信息。

项目结构

.
├── 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

实现说明

• 关键词使用支持 Unicode 的边界进行解析，最多支持 20 个逗号分隔的关键词，同时拒绝句子式输入。
• 增强的检测机制可区分关键词列表（含分隔符）和自然语言句子（以空格分隔的短语）。
• FlexSearch 会为图标名称、标签、用法和类别建立索引；字段权重和词元匹配共同决定确定性评分。
• 固定返回前 5 条结果，提供重点明确且相关的匹配项，无需复杂配置。
• 应用层整合解析器验证、仓库查询和响应格式化，让接口只需处理传输相关事宜。
• MCP 响应包含自然语言指导和机器可读的匹配项，让 LLM 客户端能够准确选择一个图标。
• CLI 运行器支持通过 npx 或全局安装独立运行，便于集成。

开发脚本

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

许可证

MIT 许可证