SF Symbols

Ferramenta MCP e de linha de comando para SF Symbols

Documentação

sfsymbols-mcp

Uma ferramenta de linha de comando para macOS e servidor do Model Context Protocol para os SF Symbols da Apple. Ela pode:

Listar todos os nomes de SF Symbols do sistema (mais de 9.000).
Pesquisar símbolos por nome, palavra-chave ou alias.
Exportar qualquer símbolo para um SVG vetorial verdadeiro — dados reais de <path> bezier, não uma imagem rasterizada.

Os contornos vetoriais são as curvas exatas que a Apple fornece, extraídas diretamente do catálogo de símbolos do sistema, para que os SVGs exportados sejam dimensionados perfeitamente para qualquer tamanho.

Requisitos

macOS 14 (Sonoma) ou posterior — a ferramenta lê o catálogo de SF Symbols no disco da Apple, portanto só roda no macOS.
Toolchain Swift 6.3+ (Xcode 26 / a toolchain Swift correspondente) para compilar a partir do código-fonte.

Nota: A exportação de SVG usa a API privada do catálogo CoreUI da Apple para ler os dados de glifos vetoriais. Funciona no macOS atual, mas é indocumentada e pode mudar em futuras versões do sistema operacional.

Instalação

Homebrew + Mint

Mint instala ferramentas de linha de comando Swift diretamente de um repositório Git:

brew install mint
mint install svedm/sfsymbols-mcp

Isso compila e vincula sfsymbols-mcp ao diretório bin do Mint (geralmente ~/.mint/bin, ou /usr/local/bin se você executar mint link). Você também pode executá-lo sem instalar:

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

A partir do código-fonte

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

O binário é gerado em .build/release/sfsymbols-mcp. Opcionalmente, copie-o para o seu PATH:

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

Uso da CLI

O executável tem quatro subcomandos. Executá-lo sem argumentos inicia o servidor MCP (serve é o subcomando padrão).

Listar símbolos

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

A contagem total é gravada em stderr; os nomes vão para stdout (um por linha).

Pesquisar símbolos

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

Os resultados são classificados: correspondência exata de nome primeiro, depois correspondências de prefixo, depois correspondências de substring, depois correspondências de palavra-chave/alias.

Exportar para 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

Opções:

Opção	Valores	Padrão
`--weight`	`ultralight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black`	`regular`
`--point-size`	qualquer número (define a escala de coordenadas do contorno)	`100`
`--fill`	qualquer cor SVG, por exemplo, `currentColor`, `#FF0000`, `black`	`currentColor`
`--output`, `-o`	caminho do arquivo; se omitido, o SVG é impresso em stdout	—

O viewBox do SVG é a caixa delimitadora intrínseca do símbolo e fill tem como padrão currentColor, portanto herda a cor do texto ao redor quando incorporado em HTML ou outro SVG.

Servidor MCP

Inicie o servidor via stdio:

sfsymbols-mcp serve
# or simply:
sfsymbols-mcp

Adicione-o ao Claude Code (a CLI `claude`)

A maneira mais simples — um comando. Use o caminho completo para o binário se ele não estiver no seu PATH:

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

Se você instalou com Mint, obtenha o caminho exato com:

mint which sfsymbols-mcp

Isso registra o servidor apenas para o projeto atual (o escopo padrão local). Para disponibilizá-lo em todos os projetos, adicione --scope user:

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

Verifique e remova com:

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

Em seguida, inicie claude; execute /mcp em uma sessão para confirmar que o servidor sfsymbols está conectado.

Adicione-o via arquivo de configuração

Prefere editar um arquivo? Crie .mcp.json na raiz do seu projeto (este é o escopo do projeto que o Claude Code lê, e você pode commitá-lo para compartilhar com a equipe):

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

O mesmo JSON funciona para outros clientes MCP, por exemplo, o claude_desktop_config.json do Claude Desktop.

Ferramentas

Ferramenta	Argumentos	Retorna
`list_symbols`	`limit` (int, opcional), `offset` (int, opcional)	JSON: `total`, `offset`, `count`, `symbols[]`
`search_symbols`	`query` (string, obrigatório), `limit` (int, opcional)	JSON: `query`, `count`, `symbols[]`
`export_symbol`	`name` (string, obrigatório), `weight` (string, opcional), `point_size` (number, opcional), `fill` (string, opcional)	O documento SVG como texto

Erros (símbolo desconhecido, argumentos ausentes) são retornados como resultados de ferramenta com isError: true.

Como funciona

Listar / pesquisar leem os plists do catálogo do sistema em /System/Library/CoreServices/CoreGlyphs.bundle/Contents/Resources/ (name_availability.plist, symbol_search.plist, name_aliases.strings).
Exportar carrega o catálogo de ativos do SF Symbols (Assets.car) através do CUICatalog do CoreUI, solicita o glifo vetorial nomeado para o peso fornecido, lê seu CGPath e serializa o caminho em dados SVG <path>. O caminho do CoreUI já está na orientação SVG (Y para baixo), portanto nenhuma inversão de coordenadas é aplicada.

Desenvolvimento

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

Licença

Os próprios SF Symbols são fornecidos pela Apple e estão sujeitos ao licenciamento da Apple. Esta ferramenta apenas lê o catálogo já presente no seu Mac; ela não redistribui os ativos da Apple.