SFSymbolsMCP

An MCP server that exposes Apple's SF Symbols catalog to language models. It reads the metadata bundled with the SF Symbols app and serves three read-only tools: symbol search, platform availability, and alias lookup.

Requirements

• macOS 13 or later
• Swift 6.2 toolchain
• The SF Symbols app installed (the server reads its bundled metadata; nothing is fetched at runtime)

Build

swift build -c release

The executable is produced at .build/release/SFSymbolsMCP. It speaks MCP over stdio.

Configuration

By default the server reads metadata from /Applications/SF Symbols.app/Contents/Resources/Metadata. Two environment variables override the location (the first non-empty one wins):

Variable	Points at	Example
SF_SYMBOLS_METADATA_PATH	the Metadata directory directly	/path/to/Metadata
SF_SYMBOLS_APP_PATH	the .app bundle (the Contents/Resources/Metadata subpath is derived)	/Applications/SF Symbols Beta.app

Connecting a client

Point your MCP client at the built binary over stdio. For example, in an .mcp.json:

{
  "mcpServers": {
    "sf-symbols": {
      "command": "/absolute/path/to/.build/release/SFSymbolsMCP"
    }
  }
}

To target a beta install, add an env block:

{
  "mcpServers": {
    "sf-symbols": {
      "command": "/absolute/path/to/.build/release/SFSymbolsMCP",
      "env": { "SF_SYMBOLS_APP_PATH": "/Applications/SF Symbols Beta.app" }
    }
  }
}

Claude Code

Register the server once for all projects (user scope):

claude mcp add -s user sf-symbols -- /absolute/path/to/.build/release/SFSymbolsMCP

To target a beta install, add the env override:

claude mcp add --env 'SF_SYMBOLS_APP_PATH=/Applications/SF Symbols Beta.app' -s user sf-symbols -- /absolute/path/to/.build/release/SFSymbolsMCP

Tools

All tools are read-only.

search

Find symbols whose name, aliases, or search terms contain the query (case-insensitive substring match). Results are ordered shortest-name first.

Parameter	Type	Required	Description
query	string	yes	Text to match.
limit	integer	no	Maximum results (default 25).

Example: search(query: "microphone", limit: 5)

{
  "names": [
    "microphone",
    "microphone.fill",
    "microphone.slash",
    "music.microphone",
    "microphone.circle"
  ]
}

availability

Look up the platform availability of a symbol. Accepts a canonical name or an alias. If the name is an alias with no availability of its own, it resolves to the symbol it points at and name reports that symbol. If the alias has its own availability, name stays the requested name and aliasTarget (or legacyAliasTarget) reports the symbol it aliases. layerSetAvailability is present only for symbols that have per-layer-set availability.

Parameter	Type	Required	Description
name	string	yes	Symbol or alias name, e.g. circle.fill.

Example: availability(name: "microphone")

{
  "baseAvailability": {
    "iOS": "18.0",
    "macOS": "15.0",
    "tvOS": "18.0",
    "visionOS": "2.0",
    "watchOS": "11.0"
  },
  "layerSetAvailability": {
    "multicolor": {
      "iOS": "15.0",
      "macOS": "12.0",
      "tvOS": "15.0",
      "visionOS": "1.0",
      "watchOS": "8.0"
    }
  },
  "name": "microphone"
}

Example: availability(name: "mic")

{
  "aliasTarget": "microphone",
  "baseAvailability": {
    "iOS": "13.0",
    "macOS": "10.15",
    "tvOS": "13.0",
    "visionOS": "1.0",
    "watchOS": "6.0"
  },
  "name": "mic"
}

Unknown names return an error result (No symbol found for: …).

aliases

List the alias and legacy alias names that refer to a symbol.

Parameter	Type	Required	Description
name	string	yes	Symbol or alias name.

Example: aliases(name: "microphone")

{
  "aliases": [
    "mic"
  ],
  "legacyAliases": []
}

Project layout

• SFSymbolsKit — a standalone library that loads the SF Symbols metadata and answers queries (search, details, availability resolution, alias lookup). No MCP dependency.
• SFSymbolsMCP — the executable that wraps SFSymbolsKit in an MCP server.