Icon Composer MCP

---

Demo

Key Features

• Create .icon bundles programmatically from PNG or SVG glyphs
• Full Liquid Glass support: specular highlights, blur material, shadows, translucency
• Dark mode + appearance variants with per-appearance fill specializations
• AI-agent ready: 12 MCP tools + 3 workflow prompts with built-in instructions

Installation

 

claude mcp add icon-composer -- npx -y icon-composer-mcp

 

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "icon-composer": {
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

 

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "icon-composer": {
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

The server will appear in Cursor Settings > MCP Servers. No restart required.

 

Add to .vscode/mcp.json in your project root (or open Command Palette > MCP: Open User Configuration for global):

Note: VS Code uses "servers" (not "mcpServers") and requires a "type" field.

{
  "servers": {
    "icon-composer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

You'll see Start/Stop/Restart buttons inline in the editor. First launch will prompt a trust confirmation.

 

First, enable MCP in Windsurf Settings > Cascade > Model Context Protocol (MCP).

Then add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "icon-composer": {
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

Press the refresh button in Windsurf settings to load the server.

 

The server uses stdio transport. Most MCP clients use this config format:

{
  "mcpServers": {
    "icon-composer": {
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

Or run the server directly:

npx -y icon-composer-mcp

 

npm install -g icon-composer-mcp
icon-composer --help

How It Works

1. Provide a glyph — any PNG or SVG logo/image
2. Create a .icon bundle — sets background fill, layer scale, and glass effects
3. Apple's ictool renders Liquid Glass — specular highlights, shadows, depth, and translucency
4. Export — preview PNGs, App Store marketing icon, or the .icon bundle for Xcode

Requirements

• Node.js 18+
• macOS with Icon Composer for Liquid Glass rendering

  brew install --cask icon-composer
  

• Flat previews, bundle creation/editing, and marketing export work on any platform without Icon Composer

Run icon-composer doctor to check your setup.

CLI Commands

Command	Description
create	Create a new .icon bundle from a foreground image
add-layer	Add a layer to an existing bundle
remove	Remove a layer or group
inspect	Read and display bundle contents
glass	Configure Liquid Glass effects on a group
appearance	Set dark/tinted mode overrides
fill	Set background fill (solid, gradient, automatic, none)
position	Set layer/group scale and offset
fx	Toggle all glass effects on/off
preview	Export a preview PNG (Liquid Glass or flat)
render	Render pixel-perfect Liquid Glass via ictool
export-marketing	Export flat 1024x1024 PNG for App Store Connect (no alpha)
doctor	Check system setup and dependencies

Details

 

icon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]

Option	Default	Description
--bg-color <hex>	required	Background color (e.g. "#0A66C2")
--bundle-name <name>	AppIcon	Bundle name (without .icon extension)
--dark-bg-color <hex>	—	Dark mode background color
--glyph-scale <n>	1.0	Glyph scale (1.0 = standard ~65% of icon area)
--specular / --no-specular	true	Specular highlight
--shadow-kind <kind>	layer-color	Shadow type: neutral, layer-color, none
--shadow-opacity <n>	0.5	Shadow opacity (0–1)
--blur-material <n>	—	Blur material value (0–1)
--translucency-enabled	false	Enable translucency gradient
--translucency-value <n>	0.4	Translucency amount (0–1)

Output: Creates <output_dir>/<bundle_name>.icon/ containing icon.json manifest and Assets/ directory.

 

icon-composer add-layer <bundle_path> <image_path> --name <name> [options]

Option	Default	Description
--name <name>	required	Layer name
--group-index <n>	0	Target group index
--create-group	false	Create a new group for this layer
--opacity <n>	1.0	Layer opacity (0–1)
--scale <n>	1.0	Layer scale
--offset-x <n>	0	X offset in points
--offset-y <n>	0	Y offset in points
--blend-mode <mode>	normal	Blend mode (e.g. multiply, screen, overlay)
--glass / --no-glass	true	Participate in Liquid Glass effects

Supported formats: .png, .jpg, .jpeg, .svg, .webp, .heic, .heif

 

icon-composer remove <bundle_path> --target <layer|group> --group-index <n> [--layer-index <n>]

 

icon-composer inspect <bundle_path>

Output: Prints the full manifest JSON and lists all assets with sizes.

 

icon-composer glass <bundle_path> [options]

Option	Description
--group-index <n>	Target group (default: 0)
--specular / --no-specular	Specular highlight
--blur-material <n>	Blur amount (0–1)
--shadow-kind <kind>	neutral, layer-color, or none
--shadow-opacity <n>	Shadow opacity (0–1)
--translucency-enabled / --no-translucency-enabled	Translucency toggle
--translucency-value <n>	Translucency amount (0–1)
--opacity <n>	Group opacity (0–1)
--blend-mode <mode>	Group blend mode
--lighting <type>	combined or individual

 

icon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]

Option	Description
--target <type>	fill (background color), group (glass effects), or layer (individual layer)
--appearance <mode>	dark or tinted
--group-index <n>	Group index (for target=group or target=layer)
--layer-index <n>	Layer index within the group (required when target=layer)
--bg-color <hex>	Background color for this appearance
--specular / --no-specular	Specular for this appearance
--shadow-kind <kind>	Shadow type for this appearance
--shadow-opacity <n>	Shadow opacity for this appearance
--opacity <n>	Opacity for this appearance
--blur-material <n>	Blur material value (0–1) for this appearance
--translucency-enabled / --no-translucency-enabled	Translucency toggle for this appearance
--translucency-value <n>	Translucency amount (0–1) for this appearance
--hidden / --no-hidden	Hidden state for this appearance
--blend-mode <mode>	Blend mode for this appearance (target=layer)
--fill-color <hex>	Fill color for this appearance (target=layer)
--position-scale <n>	Position scale for this appearance
--position-offset-x <n>	Position X offset for this appearance
--position-offset-y <n>	Position Y offset for this appearance

 

icon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]

Option	Description
--type <type>	solid, gradient, automatic, or none
--color <hex>	Primary color (for solid or gradient bottom)
--color2 <hex>	Secondary color (gradient top)
--gradient-angle <n>	Gradient angle in degrees (default: 0)

 

icon-composer position <bundle_path> [options]

Option	Default	Description
--target <type>	layer	layer or group
--group-index <n>	0	Group index
--layer-index <n>	—	Layer index (required for --target layer)
--scale <n>	—	Scale factor (0.05–3.0)
--offset-x <n>	—	X offset in points
--offset-y <n>	—	Y offset in points

 

icon-composer fx <bundle_path> --enable|--disable

Enables or disables specular, shadow, blur, and translucency on every group at once.

 

icon-composer preview <bundle_path> <output_path> [options]

Option	Default	Description
--size <n>	1024	Output size in pixels
--appearance <mode>	—	dark or tinted
--flat	false	Force flat rendering (skip Liquid Glass)
--canvas-bg <preset>	—	light, dark, checkerboard, homescreen-light, homescreen-dark
--apple-preset <name>	—	Apple wallpaper: sine-purple-orange, sine-gasflame, sine-magenta, sine-green-yellow, sine-purple-orange-black, sine-gray
--canvas-bg-color <hex>	—	Custom background color
--canvas-bg-image <path>	—	Custom background image
--zoom <n>	1.0	Zoom level (icon size relative to canvas)

Output: PNG file. Uses Liquid Glass rendering by default (falls back to flat if Icon Composer is not installed).

 

icon-composer render <bundle_path> <output_path> [options]

Option	Default	Description
--platform <name>	iOS	iOS, macOS, or watchOS
--rendition <name>	Default	Default, Dark, TintedLight, TintedDark, ClearLight, ClearDark
--width <n>	1024	Output width
--height <n>	1024	Output height
--scale <n>	1	Scale factor (1x, 2x, 3x)
--light-angle <n>	—	Light angle (0–360)
--tint-color <n>	—	Tint hue (0–1)
--tint-strength <n>	—	Tint strength (0–1)
Canvas options	—	Same as preview

Requires: Icon Composer.app installed. Returns an error with install instructions if missing.

 

icon-composer export-marketing <bundle_path> <output_path> [--size <n>]

Output: Flat PNG with no alpha channel (avoids ITMS-90717 rejection). Default 1024x1024.

 

icon-composer doctor

Output: Reports Node version, platform, ictool path and version. Prints install instructions if Icon Composer is missing.

---

MCP Tools

Tool	Description
create_icon	Create a .icon bundle from a foreground image and background color
add_layer_to_icon	Add a new layer to an existing bundle
remove_layer	Remove a layer or group, optionally clean up assets
read_icon	Inspect bundle manifest and assets
set_glass_effects	Configure specular, blur, shadow, translucency
set_appearances	Set dark/tinted mode overrides
set_fill	Set background fill
set_layer_position	Adjust layer scale and offset
toggle_fx	Enable/disable all glass effects at once
export_preview	Render a preview PNG
render_liquid_glass	Render via Apple's ictool (requires Icon Composer)
export_marketing	Export flat opaque PNG for App Store Connect

All tools return { content: [{ type: "text", text: "..." }], isError?: true }.

Details

 

Create a .icon bundle from a foreground image.

Parameter	Type	Required	Default	Description
foreground_path	string	yes	—	Absolute path to PNG or SVG
output_dir	string	yes	—	Output directory
bundle_name	string	no	AppIcon	Bundle name
bg_color	string	yes	—	Background hex color
dark_bg_color	string	no	—	Dark mode background color
glyph_scale	number	no	1.0	Glyph scale (0.1–2.0)
specular	boolean	no	true	Specular highlight
shadow_kind	enum	no	layer-color	neutral, layer-color, none
shadow_opacity	number	no	0.5	Shadow opacity (0–1)
blur_material	number	no	—	Blur amount (0–1)
translucency_enabled	boolean	no	false	Enable translucency
translucency_value	number	no	0.4	Translucency amount (0–1)

 

add_layer_to_icon

Add a layer to an existing bundle.

Parameter	Type	Required	Default	Description
bundle_path	string	yes	—	Path to .icon bundle
image_path	string	yes	—	Path to image file
layer_name	string	yes	—	Layer name
group_index	number	no	0	Target group
create_group	boolean	no	false	Create new group
opacity	number	no	1.0	Layer opacity (0–1)
scale	number	no	1.0	Layer scale (0.1–2.0)
offset_x	number	no	0	X offset
offset_y	number	no	0	Y offset
blend_mode	enum	no	normal	Blend mode
glass	boolean	no	true	Glass participation

 

remove_layer

Remove a layer or group. layer_index required when target=layer.

Parameter	Type	Required	Default
bundle_path	string	yes	—
target	enum	yes	—
group_index	number	yes	—
layer_index	number	no	—
cleanup_assets	boolean	no	true

 

read_icon

Inspect a bundle. Returns full manifest JSON and asset list with sizes.

Parameter	Type	Required
bundle_path	string	yes

 

set_glass_effects

Configure Liquid Glass on a group. All effect parameters are optional — only provided values are changed.

Parameter	Type	Default	Description
bundle_path	string	—	Path to bundle
group_index	number	0	Target group
specular	boolean	—	Specular toggle
blur_material	number|null	—	Blur (0–1, null to disable)
shadow_kind	enum	—	neutral, layer-color, none
shadow_opacity	number	—	Shadow opacity (0–1)
translucency_enabled	boolean	—	Translucency toggle
translucency_value	number	—	Translucency amount (0–1)
opacity	number	—	Group opacity (0–1)
blend_mode	enum	—	Blend mode
lighting	enum	—	combined or individual

 

set_appearances

Set dark/tinted overrides for background fill, group effects, or individual layer properties.

Parameter	Type	Required	Description
bundle_path	string	yes	Path to bundle
target	enum	yes	fill, group, or layer
appearance	enum	yes	dark or tinted
group_index	number	no	Group index (for target=group or target=layer)
layer_index	number	no	Layer index within the group (required when target=layer)
bg_color	string	no	Background color for this appearance (target=fill)
specular	boolean	no	Specular for this appearance (target=group)
shadow_kind	enum	no	Shadow type (target=group)
shadow_opacity	number	no	Shadow opacity (target=group)
opacity	number	no	Opacity for this appearance (target=group or target=layer)
blur_material	number|null	no	Blur material for this appearance (target=group)
translucency_enabled	boolean	no	Enable translucency for this appearance (target=group)
translucency_value	number	no	Translucency amount for this appearance (target=group)
hidden	boolean	no	Hidden state for this appearance (target=group or target=layer)
blend_mode	enum	no	Blend mode for this appearance (target=layer)
fill_color	string	no	Fill color hex for this appearance (target=layer)
position_scale	number	no	Position scale for this appearance (0.05–3.0)
position_offset_x	number	no	Position X offset for this appearance
position_offset_y	number	no	Position Y offset for this appearance

 

set_fill

Set background fill.

Parameter	Type	Required	Description
bundle_path	string	yes	Path to bundle
fill_type	enum	yes	solid, gradient, automatic, none
color	string	no	Hex color (solid or gradient bottom)
color2	string	no	Gradient top color
gradient_angle	number	no	Angle in degrees (default: 0)

 

set_layer_position

Adjust layer or group scale and offset.

Parameter	Type	Default	Description
bundle_path	string	—	Path to bundle
target	enum	layer	layer or group
group_index	number	0	Group index
layer_index	number	—	Layer index (for target=layer)
scale	number	—	Scale (0.05–3.0)
offset_x	number	—	X offset
offset_y	number	—	Y offset

 

toggle_fx

Enable or disable all glass effects on every group.

Parameter	Type	Required
bundle_path	string	yes
enabled	boolean	yes

 

export_preview

Render a preview PNG. Uses Liquid Glass by default, falls back to flat.

Parameter	Type	Default	Description
bundle_path	string	—	Path to bundle
output_path	string	—	Output PNG path
size	number	1024	Output size (16–2048)
appearance	enum	—	dark or tinted
flat	boolean	false	Force flat rendering
canvas_bg	enum	—	Preset background
apple_preset	enum	—	Apple wallpaper preset
canvas_bg_color	string	—	Custom background hex
canvas_bg_image	string	—	Background image path
zoom	number	1.0	Zoom level (0.1–3.0)
return_image	boolean	true	Return rendered image inline as base64

 

render_liquid_glass

Pixel-perfect Liquid Glass via Apple's ictool. Requires Icon Composer.app.