qingicon-mcp

qingicon-mcp（中文版）

QingIcon 的 MCP server。让 AI 编码工具（Cursor、Claude Code、Codex、VS Code Copilot 等）直接搜索 QingIcon 图标，并生成可粘贴的 React / Vue 组件代码，或纯 HTML 内联 SVG。

• 中文感知搜索：基于中文分词与模糊匹配，天然支持「早蛋」命中「早餐 + 鸡蛋」、「一碗食物」跨关键词召回。
• 中英文混合：英文手滑也能兜底（如 pecil → pencil 系）。
• 框架感知：同时覆盖 React / Vue，对齐官方 qingicon-react / qingicon-vue 包。
• 即取即用：search_icons 负责「找」，返回候选；get_icon_code 负责「出码」，按 framework 返回 React / Vue 组件代码，或纯 HTML 内联 <svg>。
• 纯工具层、数据全在云端：本包不内置任何图标数据。搜索索引与 SVG 来自官方 CDN。

安装

npx qingicon-mcp

或全局安装：

npm install -g qingicon-mcp

接入客户端

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "qingicon": {
      "command": "npx",
      "args": ["-y", "qingicon-mcp"]
    }
  }
}

重启 Claude Desktop 后，工具即可在对话中使用。

Claude Code / Codex / Cursor

claude mcp add --transport stdio qingicon -- npx -y qingicon-mcp
# 或
codex mcp add qingicon -- npx -y qingicon-mcp

Cursor 在 Settings → MCP → Add Server 中填入同样的 stdio 配置即可。

工具

风格说明：MCP 只生成 npm 包支持的 line / fill（sketch 为官网在线能力，不在 npm 包内）。

SVG 数据来源与 fill 预留：get_icon_code 的 html 模式按需拉取 CDN 分类分片，按 id 提取该图标的内联 <svg>（会话内按「变体 × 分类」缓存，同分类后续图标 0 额外下载）。fill 变体预留完成：当 fill 源文件进入图标库并上 CDN 后，分片里会出现 data-style="fill-*"，html / react / vue 指定 variant="fill" 即自动生效；在此之前请求 fill 会提示「该变体数据未托管于 CDN」，属数据尚未就绪，非缺陷。

真实使用场景

以下示例中的图标名与返回结果均经过实测，可直接照用。

场景 1：React 项目里给登录入口加用户图标

用户在 Cursor 中说：「给登录入口加个用户图标」。

AI 调用 search_icons：

{ "keyword": "account", "limit": 5 }

返回候选（不含代码，由 get_icon_code 负责出码）：

• QiHomeUser  (id: home-user)
  分类: Building
  关键词: house, mainpage, startpage, residence...

确定用 QiHomeUser 后，AI 调用 get_icon_code：

{ "name": "home-user", "framework": "react", "size": 20 }

拿到完整片段并写入文件：

import { QiHomeUser } from "qingicon-react";

<QiHomeUser variant="line" size={20} color="currentColor" />

场景 2：Vue 项目里给收藏按钮配图标

用户：「这个收藏按钮用星形图标」。

AI 调用 search_icons({ "keyword": "收藏" }) → 命中 QiSquareStar；再调用 get_icon_code({ "name": "square-star", "framework": "vue" })：

<script setup>
import { QiSquareStar } from "qingicon-vue";
</script>

<template>
  <QiSquareStar variant="line" :size="24" color="currentColor" />
</template>

场景 3：中文模糊搜索「早蛋」

用户记不清图标名，只说：「找一个早蛋相关的图标」。

AI 调用 search_icons({ "keyword": "早蛋" })，中文分词会把「早蛋」拆成「早 / 蛋」，跨关键词命中同时含「早餐」与「鸡蛋」语义的图标，例如 QiEgg / QiEggCrack。无需用户知道确切英文 id。

场景 4：英文手滑「pecil」

用户：「加个 pecil 图标（应该是铅笔）」。

AI 调用 search_icons({ "keyword": "pecil" })，模糊兜底命中 QiModelPencil 等 pencil 系图标——AI 不必因为拼写错误就放弃或瞎猜。

场景 5：已知组件名，直接取码

用户从官网复制了 <QiCarDoor />，想在代码里用。

AI 调用 get_icon_code({ "name": "QiCarDoor", "framework": "react" })，QiCarDoor 会被正确反解为 id car-door 并生成：

import { QiCarDoor } from "qingicon-react";

<QiCarDoor variant="line" size={24} color="currentColor" />

场景 6：把图标内联进纯 HTML / 邮件

用户：「把这个搜索图标的内联 SVG 给我，我要贴进邮件模板 / 纯 HTML 页面」。场景里没有 React/Vue，用组件不合适。

AI 调用 get_icon_code({ "name": "search", "framework": "html" })，返回可直接内联的 <svg> 字符串（已转 currentColor，跟随页面 CSS color 变色）：

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none"><g data-style="line">...</g></svg>

场景 7：指定风格与颜色

用户：「心形破碎图标用品牌绿色实心」。

AI 调用 get_icon_code({ "name": "heart-crack", "framework": "react", "variant": "fill", "color": "#15a675" })：

import { QiHeartCrack } from "qingicon-react";

<QiHeartCrack variant="fill" size={24} color="#15a675" />

场景 8：多词 AND 精确收窄

用户：「找一个同时跟『用户』和『设置』相关的图标」。

AI 调用 search_icons({ "keyword": "用户 设置" })，只有同时命中两个词的图标才会被召回，避免返回一大堆只含「用户」或只含「设置」的噪声，例如 QiUserSettings。

数据流

• 本包是纯工具层，不含任何图标数据。
• 搜索索引：启动即从 cdn icons-index.json 拉取。
• SVG（get_icon_code 的 html 模式）：按需拉取 CDN 分类分片 icons/{variant}/{分类}.json，按 id 提取内联 <svg>；分片在 MCP 进程内存中按「变体 × 分类」缓存，同分类后续图标不再重复下载。所有取数均运行时来自 CDN，本包零内置、零离线数据，且不落盘。
• 网络不可达时：搜索会提示索引未就绪；SVG 取数失败会提示 CDN 不可达。

链接与致谢

• 官网： qingicon.com
• 作者： Asorn
• Github： qingicon-open
• 联系： cjl294114430@gmail.com
• 协议： Apache-2.0

QingIcon 是开源项目，欢迎通过上述方式提建议与反馈。