io.github.ethbak/icon-composer-mcp MCP Server

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/banner-light.png"> <img alt="icon-composer-mcp" src="assets/banner-light.png" width="700"> </picture> </p> <h1 align="center">Icon Composer MCP</h1> <p align="center"> CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple . </p> <p align="center"> <a href="https://www.npmjs.com/package/icon-composer-mcp"><img src="https://img.shields.io/npm/v/icon-composer-mcp" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/npm/l/icon-composer-mcp" alt="license"></a> <img src="https://img.shields.io/badge/platform-macOS-blue" alt="platform"> <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible"> <a href="https://glama.ai/mcp/servers/ethbak/icon-composer-mcp"><img src="https://glama.ai/mcp/servers/ethbak/icon-composer-mcp/badges/score.svg" alt="Glama score"></a> </p>

---

Demo

<p align="center"> <img alt="demo" src="assets/demo.gif" width="650"> </p>

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

<details open> <summary>&nbsp;&nbsp;<img src="https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-svg/icons/claudecode-color.svg" width="16" height="16">&nbsp;<b>Claude Code</b></summary>

 

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

</details> <details> <summary>&nbsp;&nbsp;<img src="https://cdn.simpleicons.org/claude/D97757" width="16" height="16">&nbsp;<b>Claude Desktop</b></summary>

 

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

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

</details> <details> <summary>&nbsp;&nbsp;<picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/cursor/FFFFFF"><source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/cursor/000000"><img src="https://cdn.simpleicons.org/cursor/000000" width="16" height="16"></picture>&nbsp;<b>Cursor</b></summary>

 

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.

</details> <details> <summary>&nbsp;&nbsp;<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vscode/vscode-original.svg" width="16" height="16">&nbsp;<b>VS Code</b></summary>

 

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.

</details> <details> <summary>&nbsp;&nbsp;<picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/windsurf/FFFFFF"><source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/windsurf/0B100F"><img src="https://cdn.simpleicons.org/windsurf/0B100F" width="16" height="16"></picture>&nbsp;<b>Windsurf</b></summary>

 

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.

</details> <details> <summary>&nbsp;&nbsp;<b>Other MCP clients</b></summary>

 

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

</details> <details> <summary>&nbsp;&nbsp;<b>CLI only (no MCP)</b></summary>

 

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

</details>

How It Works

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/how-it-works-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/how-it-works-light.png"> <img alt="how it works" src="assets/how-it-works-light.png" width="700"> </picture> </p>

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

<details> <summary><b><code>create</code></b> — Create a new <code>.icon</code> bundle</summary>

 

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.

</details> <details> <summary><b><code>add-layer</code></b> — Add a layer to an existing bundle</summary>

 

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

</details> <details> <summary><b><code>remove</code></b> — Remove a layer or group</summary>

 

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

</details> <details> <summary><b><code>inspect</code></b> — Read and display bundle contents</summary>

 

icon-composer inspect <bundle_path>

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

</details> <details> <summary><b><code>glass</code></b> — Configure Liquid Glass effects</summary>

 

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

</details> <details> <summary><b><code>appearance</code></b> — Set dark/tinted mode overrides</summary>

 

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

</details> <details> <summary><b><code>fill</code></b> — Set background fill</summary>

 

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)

</details> <details> <summary><b><code>position</code></b> — Set layer/group scale and offset</summary>

 

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

</details> <details> <summary><b><code>fx</code></b> — Toggle all glass effects</summary>

 

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

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

</details> <details> <summary><b><code>preview</code></b> — Export a preview PNG</summary>

 

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).

</details> <details> <summary><b><code>render</code></b> — Render Liquid Glass via ictool</summary>

 

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.

</details> <details> <summary><b><code>export-marketing</code></b> — Export for App Store Connect</summary>

 

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

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

</details> <details> <summary><b><code>doctor</code></b> — Check system setup</summary>

 

icon-composer doctor

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

</details>

---

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

<details> <summary><b><code>create_icon</code></b></summary>

 

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)

</details> <details> <summary><b><code>add_layer_to_icon</code></b></summary>

 

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

</details> <details> <summary><b><code>remove_layer</code></b></summary>

 

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

</details> <details> <summary><b><code>read_icon</code></b></summary>

 

read_icon

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

Parameter	Type	Required
bundle_path	string	yes

</details> <details> <summary><b><code>set_glass_effects</code></b></summary>

 

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

</details> <details> <summary><b><code>set_appearances</code></b></summary>

 

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

</details> <details> <summary><b><code>set_fill</code></b></summary>

 

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)

</details> <details> <summary><b><code>set_layer_position</code></b></summary>

 

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

</details> <details> <summary><b><code>toggle_fx</code></b></summary>

 

toggle_fx

Enable or disable all glass effects on every group.

Parameter	Type	Required
bundle_path	string	yes
enabled	boolean	yes

</details> <details> <summary><b><code>export_preview</code></b></summary>

 

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

</details> <details> <summary><b><code>render_liquid_glass</code></b></summary>

 

render_liquid_glass

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

Parameter	Type	Default	Description
bundle_path	string	—	Path to bundle
output_path	string	—	Output PNG path
platform	enum	iOS	iOS, macOS, watchOS
rendition	enum	Default	Default, Dark, TintedLight, TintedDark, ClearLight, ClearDark
width	number	1024	Output width (16–2048)
height	number	1024	Output height (16–2048)
scale	number	1	Scale factor (1–3)
light_angle	number	—	Light angle (0–360)
tint_color	number	—	Tint hue (0–1)
tint_strength	number	—	Tint strength (0–1)
Canvas options	—	—	Same as export_preview
return_image	boolean	true	Return rendered image inline as base64

</details> <details> <summary><b><code>export_marketing</code></b></summary>

 

export_marketing

Flat marketing PNG for App Store Connect. No glass effects, no alpha channel.

Parameter	Type	Default	Description
bundle_path	string	—	Path to bundle
output_path	string	—	Output PNG path
size	number	1024	Output size (16–2048)
return_image	boolean	true	Return rendered image inline as base64

</details>

---

MCP Prompts

Prompt	Parameters	Description
create-app-icon	image_path, output_dir, brand_color, dark_color?	Guided workflow: create icon from a logo, preview, iterate, export
add-dark-mode	bundle_path, dark_color	Add dark mode to an existing icon with before/after preview
export-for-app-store	bundle_path, output_dir	Export marketing PNG + preview for App Store submission

Example Workflows

Create a branded icon

# Create with brand color
icon-composer create logo.svg ./out --bg-color "#0A66C2"

# Add dark mode
icon-composer appearance ./out/AppIcon.icon --target fill --appearance dark --bg-color "#0D1B2A"

# Configure glass effects
icon-composer glass ./out/AppIcon.icon --specular --shadow-kind layer-color --blur-material 0.3

# Preview
icon-composer preview ./out/AppIcon.icon preview.png

Export for App Store

# Marketing icon (flat, no alpha, 1024x1024)
icon-composer export-marketing ./out/AppIcon.icon marketing.png

# The .icon bundle goes into your Xcode project's asset catalog

Multi-layer icon with glass

# Create base icon
icon-composer create background.svg ./out --bg-color "#1C1C2E"

# Add foreground layers
icon-composer add-layer ./out/AppIcon.icon glyph.svg --name glyph --opacity 0.8
icon-composer add-layer ./out/AppIcon.icon badge.svg --name badge --create-group

# Configure glass per group
icon-composer glass ./out/AppIcon.icon --group-index 0 --specular --blur-material 0.3
icon-composer glass ./out/AppIcon.icon --group-index 1 --specular --shadow-kind neutral

# Render Liquid Glass
icon-composer render ./out/AppIcon.icon glass-preview.png

Limitations

• Liquid Glass rendering requires macOS with Apple's Icon Composer.app installed. Flat rendering works everywhere.
• ClearLight/ClearDark renditions render against gray. Apple's glass transparency requires Metal GPU, not available via CLI.

Architecture

src/lib/          Pure library (bundle, manifest, render, ictool)
src/lib/ops-*.ts  Operations layer (MCP result format)
src/cli.ts        CLI (Commander.js, 14 commands)
src/server.ts     MCP server (thin wrapper, 12 tools + 3 prompts)

Contributing

# Install dependencies
bun install

# Run tests
bun test              # 175 unit tests
npm run test:mcp      # 16 MCP integration tests

# Build
bun run build

# Visual test gallery
bun src/cli.ts visual-test --out ./gallery