# 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.

```bash
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](https://docs.astral.sh/uv/):

```bash
uv sync
```

### Use with Claude Code (MCP)

Add to your project-level `.mcp.json`:

```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:

```bash
./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](https://docs.astral.sh/uv/)
- **SF Symbols** are built into macOS — no additional installation needed

---

## License

MIT