SF Symbols

Herramienta de línea de comandos y MCP para SF Symbols

Documentación

sfsymbols-mcp

Una herramienta de línea de comandos para macOS y un servidor de Model Context Protocol para los SF Symbols de Apple. Puede:

Listar todos los nombres de SF Symbols en el sistema (más de 9,000).
Buscar símbolos por nombre, palabra clave o alias.
Exportar cualquier símbolo a un SVG vectorial real — datos de curvas bezier <path> reales, no una imagen rasterizada.

Los contornos vectoriales son las curvas exactas que Apple incluye, extraídas directamente del catálogo de símbolos del sistema, por lo que los SVG exportados se escalan limpiamente a cualquier tamaño.

Requisitos

macOS 14 (Sonoma) o posterior — la herramienta lee el catálogo de SF Symbols en disco de Apple, por lo que solo se ejecuta en macOS.
Toolchain de Swift 6.3+ (Xcode 26 / el toolchain de Swift correspondiente) para compilar desde el código fuente.

Nota: La exportación SVG utiliza la API privada del catálogo CoreUI de Apple para leer los datos de glifos vectoriales. Funciona en macOS actual, pero no está documentada y puede cambiar en futuras versiones del sistema operativo.

Instalación

Homebrew + Mint

Mint instala herramientas de línea de comandos de Swift directamente desde un repositorio Git:

brew install mint
mint install svedm/sfsymbols-mcp

Esto compila y enlaza sfsymbols-mcp en el directorio bin de Mint (normalmente ~/.mint/bin, o /usr/local/bin si ejecutas mint link). También puedes ejecutarlo sin instalarlo:

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

Desde el código fuente

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

El binario se genera en .build/release/sfsymbols-mcp. Opcionalmente, cópialo a tu PATH:

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

Uso de la CLI

El ejecutable tiene cuatro subcomandos. Ejecutarlo sin argumentos inicia el servidor MCP (serve es el subcomando predeterminado).

Listar símbolos

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

El recuento total se escribe en stderr; los nombres van a stdout (uno por línea).

Buscar símbolos

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

Los resultados se clasifican: coincidencia exacta de nombre primero, luego coincidencias de prefijo, luego coincidencias de subcadena, y luego coincidencias de palabra clave/alias.

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

Opciones:

Opción	Valores	Predeterminado
`--weight`	`ultralight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black`	`regular`
`--point-size`	cualquier número (controla la escala de coordenadas del contorno)	`100`
`--fill`	cualquier color SVG, p. ej. `currentColor`, `#FF0000`, `black`	`currentColor`
`--output`, `-o`	ruta de archivo; si se omite, el SVG se imprime en stdout	—

El viewBox del SVG es el cuadro delimitador intrínseco del símbolo y fill predetermina a currentColor, por lo que hereda el color del texto circundante cuando se incrusta en HTML u otro SVG.

Servidor MCP

Inicia el servidor a través de stdio:

sfsymbols-mcp serve
# or simply:
sfsymbols-mcp

Añadirlo a Claude Code (la CLI de `claude`)

La forma más sencilla: un solo comando. Usa la ruta completa al binario si no está en tu PATH:

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

Si lo instalaste con Mint, obtén la ruta exacta con:

mint which sfsymbols-mcp

Eso registra el servidor solo para el proyecto actual (el ámbito local predeterminado). Para hacerlo disponible en todos los proyectos, añade --scope user:

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

Compruébalo y elimínalo con:

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

Luego inicia claude; ejecuta /mcp dentro de una sesión para confirmar que el servidor sfsymbols está conectado.

Añadirlo mediante un archivo de configuración

¿Prefieres editar un archivo? Crea .mcp.json en la raíz de tu proyecto (este es el ámbito de proyecto que Claude Code lee, y puedes confirmarlo para compartirlo con el equipo):

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

El mismo JSON funciona para otros clientes MCP, p. ej. el claude_desktop_config.json de Claude Desktop.

Herramientas

Herramienta	Argumentos	Devuelve
`list_symbols`	`limit` (int, opcional), `offset` (int, opcional)	JSON: `total`, `offset`, `count`, `symbols[]`
`search_symbols`	`query` (cadena, obligatorio), `limit` (int, opcional)	JSON: `query`, `count`, `symbols[]`
`export_symbol`	`name` (cadena, obligatorio), `weight` (cadena, opcional), `point_size` (número, opcional), `fill` (cadena, opcional)	El documento SVG como texto

Los errores (símbolo desconocido, argumentos faltantes) se devuelven como resultados de herramienta con isError: true.

Cómo funciona

Listar / buscar leen los plists del catálogo del sistema en /System/Library/CoreServices/CoreGlyphs.bundle/Contents/Resources/ (name_availability.plist, symbol_search.plist, name_aliases.strings).
Exportar carga el catálogo de recursos de SF Symbols (Assets.car) a través del CUICatalog de CoreUI, solicita el glifo vectorial nombrado para el peso dado, lee su CGPath y serializa la ruta en datos SVG <path>. La ruta de CoreUI ya está en orientación SVG (Y hacia abajo), por lo que no se aplica ninguna inversión de coordenadas.

Desarrollo

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

Licencia

Los SF Symbols en sí son proporcionados por Apple y están sujetos a la licencia de Apple. Esta herramienta solo lee el catálogo ya presente en tu Mac; no redistribuye los recursos de Apple.