Nucleo MCP Server

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:

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