Sf Symbols

sfsymbols-mcp

Apple の SF Symbols 向けの macOS コマンドラインツールおよびModel Context Protocol サーバーです。次の操作ができます。

• システム内のすべての 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 では動作しますが、文書化されておらず、今後の OS リリースで変更される可能性があります。

---

インストール

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 の使い方

実行ファイルには 4 つのサブコマンドがあります。引数なしで実行すると、MCP サーバーが起動します（デフォルトのサブコマンドは serve です）。

シンボルの一覧表示

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

合計数は stderr に、名前は stdout に出力されます（1 行に 1 つ）。

シンボルの検索

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）への追加

最も簡単な方法は、コマンドを 1 つ実行することです。バイナリが 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 は、Claude Desktop の claude_desktop_config.json など、他の MCP クライアントでも使用できます。

ツール

ツール	引数	戻り値
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 のアセットを再配布することはありません。