Sf Symbols

sfsymbols-mcp

一款 macOS 命令行工具和 Model Context Protocol 服务，用于 Apple 的 SF Symbols。它可以：

• 列出系统上的所有 SF Symbol 名称（9,000 多个）。
• 按名称、关键词或别名搜索符号。
• 将任意符号导出为真正的矢量 SVG——包含真实的贝塞尔 <path> 数据，而非栅格化图像。

这些矢量轮廓是 Apple 发布的精确曲线，直接从系统符号目录中提取，因此导出的 SVG 可无损缩放至任意尺寸。

---

要求

• macOS 14（Sonoma）或更高版本——此工具会读取 Apple 磁盘上的 SF Symbols 目录，因此只能在 macOS 上运行。
• Swift 6.3+ 工具链（Xcode 26 / 对应的 Swift 工具链），用于从源代码构建。

**注意：**SVG 导出使用 Apple 的私有 CoreUI 目录 API 来读取矢量字形数据。 它目前可在 macOS 上运行，但没有文档说明，且未来的操作系统版本可能会更改此 API。

---

安装

Homebrew + Mint

Mint 可直接从 Git 仓库安装 Swift 命令行工具：

brew install mint
mint install svedm/sfsymbols-mcp

此操作会将 sfsymbols-mcp 构建并链接到 Mint 的 bin 目录（通常为 ~/.mint/bin，如果运行 mint link，则为 /usr/local/bin）。你也可以不安装，直接运行：

mint run svedm/sfsymbols-mcp sfsymbols-mcp list --limit 10

从源代码构建

git clone https://github.com/svedm/sfsymbols-mcp.git
cd sfsymbols-mcp
swift build -c release

生成的二进制文件位于 .build/release/sfsymbols-mcp。你也可以选择将它复制到 PATH 中：

cp "$(swift build -c release --show-bin-path)/sfsymbols-mcp" /usr/local/bin/

---

CLI 用法

此可执行文件有四个子命令。不带参数运行时会启动 MCP 服务（默认子命令为 serve）。

列出符号

sfsymbols-mcp list                 # print every symbol name
sfsymbols-mcp list --limit 20      # print the first 20

总数会写入 stderr；名称会写入 stdout（每行一个）。

搜索符号

sfsymbols-mcp search heart         # by name / keyword / alias
sfsymbols-mcp search weather --limit 10

结果按以下顺序排序：完全匹配的名称、前缀匹配、子串匹配，最后是关键词／别名匹配。

导出为 SVG

# Print SVG to stdout
sfsymbols-mcp export heart.fill

# Save to a file
sfsymbols-mcp export star.fill --output star.svg

# Pick a weight and fill color
sfsymbols-mcp export gearshape.fill --weight bold --fill "#1D1D1F" -o gear.svg

选项：

选项	值	默认值
--weight	ultralight、thin、light、regular、medium、semibold、bold、heavy、black	regular
--point-size	任意数字（控制轮廓的坐标比例）	100
--fill	任意 SVG 颜色，例如 currentColor、#FF0000、black	currentColor
--output、-o	文件路径；如果省略，则将 SVG 输出到 stdout	—

SVG 的 viewBox 为符号的固有边界框，且 fill 默认为 currentColor，因此将其嵌入 HTML 或其他 SVG 时，会继承周围文本的颜色。

---

MCP 服务

通过 stdio 启动服务：

sfsymbols-mcp serve
# or simply:
sfsymbols-mcp

将其添加到 Claude Code（claude CLI）

最简单的方法——只需一条命令。如果二进制文件不在 PATH 中，请使用完整路径：

claude mcp add sfsymbols -- /usr/local/bin/sfsymbols-mcp serve

如果通过 Mint 安装，可使用以下命令获取准确路径：

mint which sfsymbols-mcp

这只会为当前项目注册服务（默认的 local 范围）。若要让所有项目都能使用，请添加 --scope user：

claude mcp add --scope user sfsymbols -- /usr/local/bin/sfsymbols-mcp serve

使用以下命令检查并移除服务：

claude mcp list              # see registered servers
claude mcp get sfsymbols     # see details for this one
claude mcp remove sfsymbols  # remove it

然后启动 claude；在会话中运行 /mcp，确认 sfsymbols 服务已连接。

通过配置文件添加

更喜欢编辑文件？在项目根目录中创建 .mcp.json（这是 Claude Code 读取的项目范围配置，你可以提交该文件以便与团队共享）：

{
  "mcpServers": {
    "sfsymbols": {
      "command": "/usr/local/bin/sfsymbols-mcp",
      "args": ["serve"]
    }
  }
}

同一份 JSON 也适用于其他 MCP 客户端，例如 Claude Desktop 的 claude_desktop_config.json。

工具

工具	参数	返回值
list_symbols	limit（int，可选）、offset（int，可选）	JSON：total、offset、count、symbols[]
search_symbols	query（string，必填）、limit（int，可选）	JSON：query、count、symbols[]
export_symbol	name（string，必填）、weight（string，可选）、point_size（number，可选）、fill（string，可选）	SVG 文档文本

错误（未知符号、缺少参数）会作为工具结果返回，并带有 isError: true。

---

工作原理

• 列出 / 搜索读取以下位置的系统目录 plist 文件： /System/Library/CoreServices/CoreGlyphs.bundle/Contents/Resources/ （name_availability.plist、symbol_search.plist、name_aliases.strings）。
• 导出通过 CoreUI 的 CUICatalog 加载 SF Symbols 资源目录（Assets.car），请求指定字重的命名矢量字形，读取其 CGPath，并将路径序列化为 SVG <path> 数据。CoreUI 路径本身已采用 SVG（Y 轴向下）方向，因此不会进行坐标翻转。

---

开发

swift build      # debug build
swift test       # run the test suite

---

许可证

SF Symbols 本身由 Apple 提供，并受 Apple 的许可条款约束。此工具仅读取 Mac 上已有的目录，不会重新分发 Apple 的资源。