RemixIcon MCP

October 25, 2025 · View on GitHub

NPM Version NPM License NPM Downloads

English | 简体中文

一个轻量级的 Model Context Protocol（MCP）服务器：用户提供简洁的图标关键词（最多 20 个），服务器即返回最相关的 5 个 Remix Icon 名称与元数据——采用 Clean Architecture 架构与 FlexSearch 本地搜索。

特性

  • 智能关键词输入：支持最多 20 个逗号分隔的关键词，同时自动拒绝自然语言描述以确保最佳搜索质量。
  • 固定返回前 5 结果：始终返回最相关的 5 个图标，帮助用户聚焦决策。
  • FlexSearch 索引：使用 FlexSearch v0.8 文档索引在本地构建高速检索。
  • Clean Architecture 分层：领域、应用、基础设施、接口层各自独立，易于测试与扩展。
  • CLI 就绪：可通过 npx remixicon-mcp 作为独立 CLI 工具运行，或集成到 MCP 客户端。
  • LLM 友好的输出：返回排序候选、命中的 token，并提示模型从结果中只选择一个图标。

快速开始

安装

# 全局安装 CLI 工具
npm install -g remixicon-mcp

# 或使用 npx 直接运行
npx remixicon-mcp

# 开发环境
pnpm install
pnpm typecheck
pnpm test

使用

作为独立 CLI 工具

你可以通过 stdio 直接运行 MCP 服务器进行测试或集成：

# 使用 npx 运行
npx remixicon-mcp

# 或全局安装后运行
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 插件（推荐）

# 在 Claude Code 中添加 marketplace 插件
/plugin marketplace add Remix-Design/remixicon-mcp

优势：

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

选项 2：手动配置

# 快速命令行设置
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

配置方式

# 快速命令行设置
codex mcp add remixicon -- npx -y remixicon-mcp

设置步骤

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

可用工具

服务器通过官方 @modelcontextprotocol/sdk 以 stdio + JSON-RPC 2.0 通信，仅提供一个工具：

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 入口，用于 npx 执行
├── src/
│   ├── cli/                        # CLI 运行器实现
│   ├── bootstrap/                  # 装配依赖，维持 Clean Architecture 分层
│   ├── domain/                     # 图标实体与关键词解析器
│   ├── application/                # 搜索用例，负责校验与排序
│   ├── infrastructure/search/      # 基于 FlexSearch 的搜索实现
│   ├── interface/mcp/              # 使用 @modelcontextprotocol/sdk 构建的 MCP 服务器
│   └── data/tags.json              # Remix Icon 搜索标签
├── tests/                          # Vitest 测试用例
├── .claude-plugin/
│   └── marketplace.json            # Claude Code 插件发现的 Marketplace 元数据
├── package.json                    # pnpm 脚本配置
└── tsconfig.json                   # 严格的 TypeScript 配置（含 Node 类型）

实现说明

  • 关键词解析器支持最多 20 个逗号分隔的关键词，同时在检测到句子式输入时直接拒绝。
  • 增强的检测逻辑能够区分关键词列表（带分隔符）和自然语言句子（空格分隔的短语）。
  • FlexSearch 对图标名称、标签、用途、分类等字段建索引，结合字段权重与 token 命中计算得分。
  • 固定返回前 5 个结果，提供聚焦且相关的匹配结果，无需复杂配置。
  • 应用层组合解析、仓库查询与响应格式化，接口层只负责传输协议。
  • MCP 响应同时提供可读提示与机器可消费的结果，确保 LLM 只选择单个图标。
  • CLI 运行器支持通过 npx 或全局安装独立执行，方便集成。

开发脚本

pnpm typecheck   # 类型检查（tsc --noEmit）
pnpm test        # 运行 Vitest
pnpm exec biome check --write --unsafe   # 使用 Biome 自动修复格式与 lint

许可证

MIT License