SF Symbols MCP Server

MCP and command line tool for SF Symbols

Documentation

sfsymbols-mcp

A macOS command-line tool and Model Context Protocol 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 installs Swift command‑line tools straight from a Git repo:

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:

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

From source

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:

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

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

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

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

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:

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

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

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:

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

Check it and remove it with:

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

{
  "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

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.