nucleo-mcp

An MCP (Model Context Protocol) server that gives Claude direct access to your local Nucleo icon library — search icons, preview them as images, and export to PDF.

How it works

Nucleo stores its icon library in two places on disk:

• SQLite database — ~/Library/Application Support/Nucleo/icons/data.sqlite3 (~54k icons with names, tags, set membership)
• SVG files — ~/Library/Application Support/Nucleo/icons/sets/{set_id}/{icon_id}.svg

This server reads those files directly. The Nucleo app does not need to be running.

PDF export uses rsvg-convert to produce proper vector PDFs at the SVG's natural dimensions with a transparent background — identical to what Nucleo exports natively.

Requirements

• macOS with Nucleo installed and at least one icon library synced
• Node.js 18+
• rsvg-convert — install via Homebrew: brew install librsvg

Installation

git clone git@github.com:julianallchin/nucleo-mcp.git
cd nucleo-mcp
npm install
npm run build

Then add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "nucleo": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nucleo-mcp/dist/index.js"]
    }
  }
}

Or for a specific project, add a .mcp.json at the repo root:

{
  "mcpServers": {
    "nucleo": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nucleo-mcp/dist/index.js"]
    }
  }
}

Tools

search_icons

Search icons by name and/or tags.

query          string   Search term (matched against name and tags)
limit          number   Max results, default 20, max 100
set_id         number   Filter by icon set ID
favorites_only boolean  Only return starred icons
variant        string   Filter by style: "outline" | "solid" | "duotone-outline" | "duotone-solid"

Results include the detected variant for each icon.

preview_icon

Returns a PNG image of the icon (rendered via resvg).

icon_id  number  Icon ID
scale    number  Zoom multiplier, default 4 (gives 96px from an 18px icon)

get_icon_svg

Returns the raw SVG source of an icon.

icon_id  number  Icon ID

export_icon_to_pdf

Exports an icon to a vector PDF at the SVG's natural dimensions with a transparent background. Suitable for use directly as an Xcode image asset.

icon_id      number  Icon ID
output_path  string  Destination path, e.g. ~/Desktop/icon.pdf

get_icon_variants

Returns all style variants of an icon by name, with PNG previews. Useful for finding the right variant to match an existing icon's visual style.

name     string  Exact icon name, e.g. "alarm-clock"
set_id   number  Limit to a specific set (optional)
preview  boolean Include PNG previews, default true

list_icon_sets

Lists all icon sets with ID, title, size(s), and icon count.

get_icons_in_set

Lists icons within a specific set.

set_id  number  Set ID
limit   number  Max results, default 50

get_favorite_icons

Returns all icons marked as favorites in Nucleo.

limit  number  Max results, default 50

Variants

Nucleo ships multiple style variants of each icon. The variant is detected from the SVG source:

Variant	Description
solid	Filled black shapes, no strokes
outline	Stroked paths, fill="none"
duotone-solid	Solid primary + semi-transparent secondary fill
duotone-outline	Stroked primary + semi-transparent secondary fill

Use get_icon_variants to see all variants of an icon side-by-side before deciding which to export.

Development

npm run dev      # run with tsx (no build step)
npm run build    # compile TypeScript to dist/
npm start        # run compiled output