better-icons

🚀 更好图标（Better Icons）

搜索并获取来自 150 多个图标集合的 200,000 多个图标。可作为 AI 代理的 MCP 服务器或 CLI 工具使用。

🚀 快速开始

添加技能

你可以使用技能启用底层图标 CLI 功能。

npx add-skill better-auth/better-icons

MCP 服务器（AI 代理）

配置 MCP 服务器，以便在你的 AI 编码代理中启用图标工具。

npx better-icons setup

此命令将交互式地为以下工具配置 MCP 服务器：

• Cursor
• Claude Code
• OpenCode
• Windsurf
• VS Code（Copilot）
• Google Antigravity

或者手动配置。

CLI（直接使用）

使用 CLI 直接从终端搜索和获取图标。

# 搜索图标
npx better-icons search arrow
npx better-icons search home --prefix lucide --limit 10

# 获取图标 SVG（输出到标准输出）
npx better-icons get lucide:home > icon.svg
npx better-icons get mdi:account --color '#333' --size 24

# 用于脚本的 JSON 输出
npx better-icons search settings --json | jq '.icons[:5]'
npx better-icons get heroicons:check --json

✨ 主要特性

• 200,000+ 图标 - 可搜索 150 多个图标集合（如 Lucide、Heroicons、Material Design 等）。
• 自动学习 - 记住你使用的图标集合，并在未来搜索中优先显示。
• 项目同步 - 图标直接写入你的图标文件（.tsx、.ts、.js），而不是将 SVG 粘贴到聊天中（节省令牌！）。
• 批量检索 - 一次获取多个图标。
• 相似图标 - 在不同集合和样式中找到相同的图标。
• 最近使用的图标 - 快速访问你之前使用过的图标。
• 多框架支持 - 支持 React、Vue、Svelte、Solid 和原始 SVG 导出。

📦 安装指南

手动安装

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "better-icons": {
      "command": "npx",
      "args": ["-y", "better-icons"]
    }
  }
}

Claude Code（CLI）

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "better-icons": {
      "command": "npx",
      "args": ["-y", "better-icons"]
    }
  }
}

Google Antigravity

添加到 ~/.gemini/antigravity/mcp_config.json：

{
  "mcpServers": {
    "better-icons": {
      "command": "npx",
      "args": ["-y", "better-icons"]
    }
  }
}

📚 详细文档

MCP 工具

使用 MCP 服务器与 AI 代理时，可使用以下工具：

search_icons

在 150 多个图标集合中搜索图标。

搜索“arrow”图标
在 lucide 集合中搜索“home”图标

参数：

• query（必需）：搜索查询（例如，'arrow'、'home'、'user'）
• limit（可选）：最大结果数（1 - 999，默认值：32）
• prefix（可选）：按集合过滤（例如，'mdi'、'lucide'）
• category（可选）：按类别过滤

get_icon

获取特定图标的 SVG 代码，支持多种使用格式。

获取 mdi:home 的 SVG
获取 mdi:home 的 URL
获取大小为 24 的 lucide:arrow-right

参数：

• icon_id（必需）：图标 ID，格式为 'prefix:name'（例如，'mdi:home'）
• color（可选）：图标颜色（例如，'#ff0000'、'currentColor'）
• size（可选）：图标大小（像素）
• format（可选）：'svg'（默认）或 'url'

返回：

• 原始 SVG 代码
• React/JSX 组件代码
• Iconify 组件使用方法
• 直接 SVG URL（当 format: "url" 时）

list_collections

列出可用的图标集合/库。

列出所有图标集合
搜索“material”集合

参数：

• category（可选）：按类别过滤
• search（可选）：按名称搜索集合

recommend_icons

获取特定用例的图标推荐。

我应该为设置按钮使用什么图标？
推荐用于用户认证的图标

参数：

• use_case（必需）：描述你的需求
• style（可选）：'solid'、'outline' 或 'any'
• limit（可选）：推荐数量（1 - 20）

get_icon_preferences

查看你学习到的图标集合偏好和使用统计信息。

显示我的图标偏好
我最常使用哪些图标集合？

clear_icon_preferences

重置所有学习到的图标偏好，重新开始。

清除我的图标偏好
重置图标偏好

find_similar_icons

在不同集合和样式中查找给定图标的相似图标或变体。

查找与 lucide:home 相似的图标
除了 mdi:arrow-right 还有哪些箭头图标？

参数：

• icon_id（必需）：要查找变体的图标 ID
• limit（可选）：相似图标的最大数量（1 - 50，默认值：10）

get_icons

一次获取多个图标（批量检索）。比多次调用 get_icon 更高效。

获取这些图标：lucide:home、lucide:settings、lucide:user

参数：

• icon_ids（必需）：图标 ID 数组（最多 20 个）
• color（可选）：所有图标的颜色
• size（可选）：所有图标的大小（像素）

get_recent_icons

查看你最近使用的图标，以便快速重用。

显示我最近使用的图标
我最近使用了哪些图标？

参数：

• limit（可选）：显示的最近图标数量（1 - 50，默认值：20）

sync_icon

获取图标并自动将其添加到项目的图标文件中。这是添加图标的推荐方法。

将 lucide:home 图标同步到我的项目
将设置图标添加到我的图标文件中

参数：

• icons_file（必需）：图标文件的绝对路径
• framework（必需）：'react'、'vue'、'svelte'、'solid' 或 'svg'
• icon_id（必需）：图标 ID，格式为 'prefix:name'
• component_name（可选）：自定义组件名称
• color（可选）：图标颜色
• size（可选）：图标大小（像素）

返回：

• 确认图标已添加（或已存在）
• 使用的导入语句
• 使用示例

scan_project_icons

扫描图标文件，查看项目中已有的图标。

我的项目中已经有哪些图标？
扫描我的图标文件

参数：

• icons_file（必需）：图标文件的绝对路径

流行图标集合

| 前缀 | 名称 | 样式 | 图标数量 | |--------|------|-------|-------| | mdi | Material Design Icons | 实心 | 7,000+ | | lucide | Lucide Icons | 轮廓 | 1,500+ | | heroicons | Heroicons | 两者皆有 | 300+ | | tabler | Tabler Icons | 轮廓 | 5,000+ | | ph | Phosphor Icons | 多种 | 9,000+ | | ri | Remix Icons | 两者皆有 | 2,800+ | | fa6-solid | Font Awesome 6 | 实心 | 2,000+ | | simple-icons | Simple Icons | 标志 | 3,000+ |

CLI 参考

搜索图标

在 150 多个图标集合中搜索。

better-icons search <query> [options]

| 选项 | 描述 | |--------|-------------| | -p, --prefix <prefix> | 按集合过滤（例如，lucide、mdi） | | -l, --limit <number> | 最大结果数（默认值：32） | | --json | 以 JSON 格式输出，用于脚本 |

获取图标

检索单个图标的 SVG 代码。

better-icons get <icon-id> [options]

| 选项 | 描述 | |--------|-------------| | -c, --color <color> | 图标颜色（例如，#ff0000、currentColor） | | -s, --size <pixels> | 图标大小（像素） | | --json | 输出包含元数据的 JSON |

图标 ID 格式为 prefix:name（例如，lucide:home、mdi:arrow-right）。

设置命令

better-icons setup              # 交互式设置向导
better-icons setup -y           # 自动确认（全局范围）
better-icons setup -s project   # 仅为当前项目设置
better-icons config             # 显示手动配置说明

| 选项 | 描述 | |--------|-------------| | -y, --yes | 跳过确认提示 | | -a, --agent <agents...> | 指定代理（cursor、claude-code、opencode、windsurf、vscode、antigravity） | | -s, --scope <scope> | 配置范围：global（默认）或 project |

🔧 技术细节

开发

# 安装依赖
bun install

# 本地运行
bun run dev

# 构建
bun run build

📄 许可证

MIT