# MCP tools

<!-- Generated by site/build.mjs from src/tools.mjs. Don't edit by hand. -->

iconwright's MCP server has 20 tools. The design tools work on any OS; the rest need Windows and only appear there.

Every tool rejects arguments it doesn't know, so a typo is an error instead of being silently ignored. Read-only tools are marked so clients can run them without asking.

**Style strings.** Tools that style an icon take one `style` argument: space-separated `key=value` pairs. Keys: `color` (recolors the artwork), `bg` (a CSS color or `linear-gradient(135deg,#a,#b)`), `shape` (`none`, `square`, `rounded`, `squircle`, `circle`), `radius` (0–0.5), `padding` (0–0.45) and `shadow`. Example: `color=white bg=#2d5ba6 shape=squircle shadow`.

## Design

### `search_icons`

Search 200,000+ open-source icons (Iconify). Returns ids and, by default, a numbered contact sheet: picture N is icons[N-1]. Brand logos: "simple-icons:<brand>".

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `query` (required) | string | What to look for, e.g. "music note" |
| `limit` | integer | Results (default 24) |
| `start` | integer | Skip this many results (next page) |
| `collections` | string[] | Only these icon sets, e.g. ["mdi", "ph", "lucide"] |
| `palette` | "mono" \| "color" | mono: single-color icons (recolor cleanly); color: multicolor |
| `preview` | boolean | Include the contact sheet (default true) |

### `design_icons`

Compare options in one small image: rows A, B, … = sources, columns 1, 2, … = styles; each cell shows the icon large and at 24 px on dark and light. Pass a picked cell's (e.g. "B2") source and style to preview_icon, make_icon or app_apply_icon. Max 36 cells. Nothing is saved.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `sources` (required) | string[] | Rows: icon ids, files, raw <svg> or "app:<name>" |
| `styles` | string[] | Columns: style strings (see make_icon), e.g. ["color=white", "color=white bg=#1DB954 shape=squircle"] |

### `preview_icon`

Mock up an icon where it lives: taskbar, start, desktop, explorer, browser, dock, ios, android, sizes (sizes = true pixels). On Windows, taskbar and start show the user's own pinned apps around it. Use before applying: catches icons that vanish on light or dark. Nothing is saved.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` (required) | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `label` | string | App name shown under the icon |
| `scenes` | "taskbar" \| "start" \| "desktop" \| "explorer" \| "browser" \| "dock" \| "ios" \| "android" \| "sizes"[] | Default taskbar, start, desktop, sizes |
| `scale` | 1 \| 1.5 \| 2 | Display scaling to mimic (default 1) |

### `make_icon`

Write icon files: ico (Windows, 16-256 px), png, icns (macOS), web (favicons, touch + PWA icons, manifest, head.html), pngset (16-1024 px). Default ico + png. Returns paths and a preview (48 and 24 px on dark and light).

Writes files only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` (required) | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string | File name (default "icon") |
| `outDir` | string | Output folder (default: iconwright's icons folder) |
| `formats` | "ico" \| "png" \| "icns" \| "web" \| "pngset"[] | Default ["ico","png"] |
| `pngSize` | integer | Size of the png (default 256) |
| `preview` | boolean | Return the preview image (default true) |

### `open_studio`

Open iconwright studio (a visual icon editor) in the user's browser, preloaded with a source and style, to fine-tune by hand. Its "Copy for your agent" button gives the user the exact source and style to paste back.

Read-only.

| Argument | Type | Description |
| --- | --- | --- |
| `source` | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `label` | string | App name shown in the scenes |
| `open` | boolean | Open the browser (default true); false just returns the link |

## Apps and taskbar

### `find_apps`

Find installed apps (Start menu). With query: matching names and AppIDs. With apps: details for each (AppID, Start menu and pinned shortcuts, Store app or not).

Read-only. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `query` | string | Part of the name; omit both to list the first 50 |
| `apps` | string[] | App names (as find_apps shows them) or AppIDs |

### `app_apply_icon`

Put an icon on apps (Start menu + pinned shortcuts; open windows update live). Give source (source "app" restyles each app's own icon, e.g. all white) or icon (existing .ico). pin:true also pins. If the result has a hint, taskbar_refresh once after all changes. Undo: restore_icons.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `apps` (required) | string[] | App names (as find_apps shows them) or AppIDs |
| `source` | string | "app" (each app's own icon), Iconify id, image file or raw <svg> |
| `icon` | string | Existing .ico/.exe/.dll to use as is |
| `iconIndex` | integer | Icon index inside icon (default 0) |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string | File name (single app) |
| `outDir` | string | Output folder (default: iconwright's icons folder) |
| `pin` | boolean | Also pin the apps |
| `refresh` | boolean | Restart Explorer at the end if pinned icons need it |
| `noRestart` | boolean | Write the change but don't restart Explorer (shows after the next restart) |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_status`

Pinned taskbar apps in order, with each one's icon file.

Read-only. Windows only.

No arguments.

### `taskbar_pins`

Change pinned apps in ONE Explorer restart: pin, unpin and move apps in a single call (the taskbar blinks; open File Explorer windows close). dryRun shows the resulting order without changing anything. Backed up first (undo: taskbar_restore_backup).

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `pin` | string[] | Apps to pin |
| `unpin` | string[] | Apps to unpin |
| `order` | string[] | Pinned apps (incl. ones being pinned) to move to position, in this order |
| `position` | integer | Where order goes: 0 = first (default), -1 = last |
| `icon` | string | An .ico for the new pin (single app) |
| `dryRun` | boolean | Only report what would happen |
| `noRestart` | boolean | Write the change but don't restart Explorer (shows after the next restart) |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_refresh`

Restart Explorer once so pinned icons reload. Only when a result says so; once, after all changes.

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `restartCooldown` | integer | Wait until this many seconds since the last Explorer restart (helps taskbar styling tools) |

### `taskbar_restore_backup`

Put the pinned-apps list back: "last" = before the latest pin change, "original" = before iconwright's first. Restarts Explorer.

Changes the PC; restarts Explorer. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `from` | "last" \| "original" | Default "last" |

## Desktop

### `desktop_info`

Desktop icons with positions (px), icon size, options, grid spacing, monitors and system icon visibility.

Read-only. Windows only.

No arguments.

### `desktop_move`

Move desktop icons to positions (snap to the grid). Coordinates as in desktop_info.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `moves` (required) | { item: string, x: integer, y: integer }[] | Each: item (name or path from desktop_info), x and y in pixels |

### `desktop_arrange`

Line up the icons on one monitor from a corner; other monitors stay put. Save a layout first (desktop_layout).

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `itemsFirst` | string[] | Items to place first, in order; the rest follow |
| `by` | "name" \| "type" \| "none" | Sort the rest (default name) |
| `corner` | "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" |  |
| `flow` | "columns" \| "rows" | Fill columns (default) or rows first |
| `monitor` | integer | 0 = primary (default) |

### `desktop_settings`

Icon size, auto-arrange, snap to grid, show/hide all icons, and which system icons (This PC, Recycle Bin, …) show. Only the options you give change.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `iconSize` | "small" \| "medium" \| "large" \| "xl" \| "huge" \| integer | small 32, medium 48, large 96, xl 128, huge 256, or px |
| `autoArrange` | boolean |  |
| `snapToGrid` | boolean |  |
| `showIcons` | boolean | false hides every desktop icon |
| `showSystemIcons` | "this-pc" \| "recycle-bin" \| "user-files" \| "network" \| "control-panel"[] |  |
| `hideSystemIcons` | "this-pc" \| "recycle-bin" \| "user-files" \| "network" \| "control-panel"[] |  |

### `desktop_apply_icon`

Change the icon of a desktop shortcut, web link, folder or system icon (this-pc, recycle-bin, …). Give source (makes an icon) or icon (existing .ico). Plain files can't have their own icon. Undo: restore_icons.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `item` (required) | string | Name or path from desktop_info, or a system icon name |
| `source` | string | Iconify id ("mdi:music"), image file, raw <svg>, or "app:<name>" (an installed app's icon; Windows) |
| `icon` | string | Existing .ico/.exe/.dll |
| `iconIndex` | integer |  |
| `style` | string | Look, "key=value ...": color=<css> (recolors art), bg=<css or linear-gradient(135deg,#a,#b)>, shape=none\|square\|rounded\|squircle\|circle, radius=0-0.5, padding=0-0.45, shadow |
| `name` | string |  |
| `outDir` | string | Output folder (default: iconwright's icons folder) |

### `desktop_layout`

save: icon positions, size and auto-arrange to a JSON file. load: put icons back where it had them (reports items that are gone).

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `action` (required) | "save" \| "load" |  |
| `file` | string | Default: iconwright's desktop-layout.json |

## Undo and checks

### `restore_icons`

Put original icons back: on apps, on desktop items, or all:true for everything iconwright changed (pins excepted; see taskbar_restore_backup). If needsRefresh, call taskbar_refresh once.

Changes the PC. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `apps` | string[] | App names (as find_apps shows them) or AppIDs |
| `desktopItems` | string[] | Desktop items or system icon names |
| `all` | boolean |  |

### `doctor`

Read-only check that the taskbar and desktop tools can work here (Windows, PowerShell, pin list, backups, taskbar mods).

Read-only. Windows only.

No arguments.

### `capture`

See a change: the taskbar (default), the desktop icons (drawn even under windows; no wallpaper), or the screen. Fails while the screen is locked.

Read-only. Windows only.

| Argument | Type | Description |
| --- | --- | --- |
| `what` | "taskbar" \| "desktop" \| "screen" |  |
| `maxWidth` | integer | Scale down to this width (default 1600; 0 = full) |

## Prompts

Clients that support MCP prompts show these as commands; in Claude Code they're in the `/` menu, marked (MCP).

- **restyle-taskbar**: Make every pinned taskbar icon match one look (e.g. all white).
- **design-icon**: Design an icon from an idea, compare options, preview it in context, then export or apply it.
- **tidy-desktop**: Back up the desktop layout, then arrange icons neatly.
- **undo-everything**: Put back every icon iconwright changed and, if wanted, the original pinned apps.