# nucleo-mcp

An MCP (Model Context Protocol) server that gives Claude direct access to your local [Nucleo](https://nucleoapp.com) 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`](https://gitlab.gnome.org/GNOME/librsvg) 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

```bash
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`):

```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:

```json
{
  "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

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