SF Symbols MCP

SF Symbols MCP

MCP server for searching and exporting Apple SF Symbols as true vector SVGs.

SF Symbols MCP lets AI agents and developers search the full SF Symbols catalog, get symbol metadata, and export any symbol as a vector SVG — real bezier paths, not rasterized images. It uses Apple's private CoreUI framework to extract the actual glyph data from the system asset catalog.

---

Quick Start

Build

Requires macOS 14+ with Xcode or Command Line Tools installed.

git clone https://github.com/ygrec-app/sf-symbols-mcp.git
cd sf-symbols-mcp
swiftc sf_symbol_cli.swift -o sf-symbol-cli -framework AppKit -framework CoreText

Install Python dependencies

Requires uv:

uv sync

Use with Claude Code (MCP)

Add to your project-level .mcp.json:

{
  "mcpServers": {
    "sf-symbols": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/sf-symbols-mcp",
        "python",
        "server.py"
      ]
    }
  }
}

Replace /path/to/sf-symbols-mcp with the actual path where you cloned the repo.

Then ask Claude: "Find me an SF Symbol for notifications" or "Export the star.fill symbol as SVG."

---

MCP Tools

| Tool | Description | |------|-------------| | search_symbols | Search SF Symbol names by name or keyword | | get_symbol_info | Get availability, related symbols, and renderability info | | export_symbol | Export a symbol as vector SVG with weight/size options | | list_symbols | List available SF Symbol names |

Export Options

| Parameter | Default | Description | |-----------|---------|-------------| | name | required | SF Symbol name (e.g. star.fill, chevron.right) | | weight | regular | ultralight, thin, light, regular, medium, semibold, bold, heavy, black | | size | 100 | Point size for rendering | | output_path | none | File path to save SVG (returns content if omitted) | | raw_coords | false | Output raw CoreGraphics Y-up coordinates instead of standard SVG Y-down |

Use from CLI

The Swift CLI can also be used directly:

./sf-symbol-cli search star
./sf-symbol-cli export star.fill --weight bold --size 200
./sf-symbol-cli export chevron.right --output ./icons/chevron.svg
./sf-symbol-cli info heart.fill
./sf-symbol-cli list --limit 50

---

How It Works

MCP Server (Python)          Swift CLI
─────────────────           ─────────────────────────────
FastMCP tool handlers  →    CoreUI private framework
                            ├── CUICatalog (Assets.car)
                            ├── CUINamedVectorGlyph
                            └── CGPath → SVG path data

SF Symbols are stored as vector glyphs in Apple's compiled asset catalog (Assets.car) inside the SFSymbols private framework. The Swift CLI uses Objective-C runtime bridging to access CUICatalog and extract CGPath bezier data, which is then converted to SVG <path d="..."> elements.

The output is true vector SVG (~1-2KB) with actual bezier curves — not rasterized PNG embedded in SVG.

---

Requirements

• macOS 14+ (Sonoma or later)
• Xcode or Command Line Tools (for Swift compiler)
• Python 3.13+ with uv
• SF Symbols are built into macOS — no additional installation needed

---

License

MIT