sf-symbol-mcp

Languages: English | 简体中文

sf-symbol-mcp is a local MCP server and CLI that lets coding agents query real SF Symbol names from the SF Symbols app installed on your Mac.

It helps Codex, Claude Code, Cursor, and other MCP clients stop guessing Image(systemName:) values before generating SwiftUI or UIKit code.

Important Legal Note

This is not an Apple project and is not affiliated with Apple.

SF Symbols and the SF Symbols app are Apple resources. This package does not distribute Apple artwork, plist metadata, generated indexes, or a complete symbol database. It reads metadata from the user's locally installed SF Symbols app and writes a local index on that user's machine.

Use SF Symbols for in-app interface icons such as tabs, toolbar buttons, list rows, and status indicators. Do not use SF Symbols directly as App Store icons, launcher icons, logos, brand marks, trademarks, or marketing logos.

Requirements

• macOS for the official SF Symbols app metadata path
• Node.js 20 or newer
• SF Symbols app installed at /Applications/SF Symbols.app, or SF_SYMBOLS_APP_PATH pointing to another .app

The CLI can also build a limited local index from a user-provided names file with --names-file.

Quick Start

npm install -g sf-symbol-mcp
sf-symbol-mcp inspect
sf-symbol-mcp build-index
sf-symbol-mcp search "income trend chart" --platform iOS --min-os 17.0
sf-symbol-mcp serve

From a local checkout:

npm install
npm run build
npm install -g .

By default, the generated index is stored outside the package:

• macOS: ~/Library/Application Support/sf-symbol-mcp/sf-symbols-index.json
• Other platforms: ~/.cache/sf-symbol-mcp/sf-symbols-index.json

Override this with:

export SF_SYMBOLS_INDEX_PATH="$HOME/.sf-symbol-mcp/sf-symbols-index.json"

Local Development

npm install
npm run build
npm test
node dist/cli.js inspect
node dist/cli.js build-index
node dist/cli.js serve

Codex Setup

After global install:

codex mcp add sf-symbols -- sf-symbol-mcp serve

From a local checkout:

npm install
npm run build
codex mcp add sf-symbols -- node /absolute/path/to/sf-symbol-mcp/dist/cli.js serve

Add the rules in AGENTS.md to Apple-platform app projects where agents should validate SF Symbols before use.

Claude / Cursor MCP Setup

Use stdio transport with the installed CLI:

{
  "mcpServers": {
    "sf-symbols": {
      "command": "sf-symbol-mcp",
      "args": ["serve"]
    }
  }
}

For a local checkout, use:

{
  "mcpServers": {
    "sf-symbols": {
      "command": "node",
      "args": ["/absolute/path/to/sf-symbol-mcp/dist/cli.js", "serve"]
    }
  }
}

CLI Reference

sf-symbol-mcp inspect
sf-symbol-mcp build-index [--output path] [--names-file path]
sf-symbol-mcp search "calendar work schedule" --platform iOS --min-os 17.0 --limit 10
sf-symbol-mcp get calendar.badge.clock --platform iOS --min-os 17.0
sf-symbol-mcp suggest --intent "premium income trend card" --tone "premium, calm, not financial trading" --platform iOS --min-os 17.0
sf-symbol-mcp validate gearshape.fill fake.symbol --platform iOS --min-os 17.0
sf-symbol-mcp scan ./MyApp
sf-symbol-mcp validate-project ./MyApp --platform iOS --min-os 17.0
sf-symbol-mcp serve

MCP Tools

• health_check: reports server health, data source, generated index state, and symbol count.
• search_symbols: searches symbols by name, keyword, category, and lightweight semantic expansion.
• get_symbol: checks whether an exact symbol exists and returns usage snippets.
• suggest_symbols: recommends symbols for a product intent and blocks logo/App icon usage.
• validate_symbols: validates symbol names and target platform compatibility.
• usage_snippet: generates SwiftUI or UIKit snippets for a symbol.

Environment Variables

• SF_SYMBOLS_APP_PATH: custom path to SF Symbols.app.
• SF_SYMBOLS_INDEX_PATH: custom path for the generated local JSON index.

Troubleshooting

SF Symbols.app not found

Install SF Symbols from Apple Developer, or set:

export SF_SYMBOLS_APP_PATH="/path/to/SF Symbols.app"

Index not found

Run:

sf-symbol-mcp build-index

If the default cache directory is not writable, use --output or SF_SYMBOLS_INDEX_PATH.

MCP server prints unexpected output

sf-symbol-mcp serve reserves stdout for MCP protocol messages. Logs and diagnostics must go to stderr. Avoid wrapping the command in scripts that print banners or debug output to stdout.

Availability looks approximate

SF Symbols metadata exposes SF Symbols release versions, not a perfect platform matrix. This project maps release years to likely Apple platform minimum versions as a practical guardrail. Verify edge cases against the SF Symbols app or Apple's documentation.

Publishing Notes

The npm package intentionally excludes local SF Symbols data. Before publishing, check:

npm run build
npm test
npm pack --dry-run

The tarball must not contain SF Symbols Names, data/generated/*, Apple plist files, .DS_Store, editor swap files, or local indexes.