# sfsymbols-mcp

A macOS command-line tool and [Model Context Protocol](https://modelcontextprotocol.io) server
for Apple's **SF Symbols**. It can:

- **List** every SF Symbol name on the system (9,000+).
- **Search** symbols by name, keyword, or alias.
- **Export** any symbol to a **true‑vector SVG** — real bezier `<path>` data, not a rasterized image.

The vector outlines are the exact curves Apple ships, extracted straight from the system symbol
catalog, so exported SVGs scale cleanly to any size.

---

## Requirements

- **macOS 14 (Sonoma) or later** — the tool reads Apple's on‑disk SF Symbols catalog, so it only
  runs on macOS.
- **Swift 6.3+ toolchain** (Xcode 26 / the matching Swift toolchain) to build from source.

> **Note:** SVG export uses Apple's private CoreUI catalog API to read the vector glyph data.
> It works on current macOS but is undocumented and may change in future OS releases.

---

## Installation

### Homebrew + Mint

[Mint](https://github.com/yonaskolb/Mint) installs Swift command‑line tools straight from a Git repo:

```sh
brew install mint
mint install svedm/sfsymbols-mcp
```

This builds and links `sfsymbols-mcp` into Mint's bin directory (usually `~/.mint/bin`, or
`/usr/local/bin` if you run `mint link`). You can also run it without installing:

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

### From source

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

The binary is produced at `.build/release/sfsymbols-mcp`. Optionally copy it onto your `PATH`:

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

---

## CLI usage

The executable has four subcommands. Running it with no arguments starts the MCP server
(`serve` is the default subcommand).

### List symbols

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

The total count is written to stderr; the names go to stdout (one per line).

### Search symbols

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

Results are ranked: exact name match first, then prefix matches, then substring matches, then
keyword/alias matches.

### Export to SVG

```sh
# 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
```

Options:

| Option | Values | Default |
|---|---|---|
| `--weight` | `ultralight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black` | `regular` |
| `--point-size` | any number (drives the outline's coordinate scale) | `100` |
| `--fill` | any SVG color, e.g. `currentColor`, `#FF0000`, `black` | `currentColor` |
| `--output`, `-o` | file path; if omitted the SVG is printed to stdout | — |

The SVG's `viewBox` is the symbol's intrinsic bounding box and `fill` defaults to `currentColor`,
so it inherits the surrounding text color when embedded in HTML or another SVG.

---

## MCP server

Start the server over stdio:

```sh
sfsymbols-mcp serve
# or simply:
sfsymbols-mcp
```

### Add it to Claude Code (the `claude` CLI)

The simplest way — one command. Use the full path to the binary if it isn't on your `PATH`:

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

If you installed with Mint, get the exact path with:

```sh
mint which sfsymbols-mcp
```

That registers the server for the current project only (the default `local` scope). To make it
available in **every** project, add `--scope user`:

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

Check it and remove it with:

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

Then start `claude`; run `/mcp` inside a session to confirm the `sfsymbols` server is connected.

### Add it via a config file

Prefer editing a file? Create `.mcp.json` in your project root (this is the project scope Claude
Code reads, and you can commit it to share with the team):

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

The same JSON works for other MCP clients, e.g. Claude Desktop's
`claude_desktop_config.json`.

### Tools

| Tool | Arguments | Returns |
|---|---|---|
| `list_symbols` | `limit` (int, optional), `offset` (int, optional) | JSON: `total`, `offset`, `count`, `symbols[]` |
| `search_symbols` | `query` (string, required), `limit` (int, optional) | JSON: `query`, `count`, `symbols[]` |
| `export_symbol` | `name` (string, required), `weight` (string, optional), `point_size` (number, optional), `fill` (string, optional) | The SVG document as text |

Errors (unknown symbol, missing arguments) are returned as tool results with `isError: true`.

---

## How it works

- **List / search** read the system catalog plists in
  `/System/Library/CoreServices/CoreGlyphs.bundle/Contents/Resources/`
  (`name_availability.plist`, `symbol_search.plist`, `name_aliases.strings`).
- **Export** loads the SF Symbols asset catalog (`Assets.car`) through CoreUI's `CUICatalog`,
  requests the named vector glyph for the given weight, reads its `CGPath`, and serializes the
  path into SVG `<path>` data. The CoreUI path is already in SVG (Y‑down) orientation, so no
  coordinate flipping is applied.

---

## Development

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

---

## License

SF Symbols themselves are provided by Apple and subject to Apple's licensing. This tool only
reads the catalog already present on your Mac; it does not redistribute Apple's assets.