Icon Composer Mcp

io.github.ethbakPublished by GitHub account ethbakv1.1.0Updated Oct 24, 2026

CLI and MCP server for creating Apple .icon bundles with Liquid Glass effects (iOS 26+)

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & Design

Overview

AI-generated overview

Creates and edits Apple .icon bundles with Liquid Glass effects, exporting preview and App Store marketing icons.

What you can do
Provides 12 MCP tools and 3 guided prompts for building Apple .icon bundles from PNG or SVG glyphs. Tools create bundles, add or remove layers and groups, set background fills, configure Liquid Glass effects such as specular, blur, shadow and translucency, and define dark or tinted appearance overrides. It can export preview PNGs, render pixel-perfect Liquid Glass through Apple's ictool, and export flat 1024x1024 marketing icons for App Store Connect.
When to use it
Useful when an assistant needs to generate or iterate on iOS 26+ app icons, logos, or branded icon sets, including dark mode variants and App Store marketing assets. Best for macOS users who want Liquid Glass rendering; flat previews and bundle editing also work elsewhere.
Requirements
Runs locally over stdio via npx icon-composer-mcp, requiring Node.js 18+. Liquid Glass rendering needs macOS with Apple's Icon Composer.app installed; flat previews, bundle creation and editing, and marketing export work on any platform. No accounts, API keys, or environment variables are declared.
Before you install
Tools write files to paths you specify, including creating, modifying, and deleting .icon bundles and their assets, and can return rendered images inline as base64. Rendering depends on Apple's ictool and Icon Composer.app, which must be installed separately. The project states it is not affiliated with Apple.

Installation

In SourceWeft

  1. Open Icon Composer Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[icon-composer-mcp]

Icon Composer MCP

CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .

[npm version] [license] [platform] [MCP compatible] [Glama score]


Demo

[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

  [Image] Claude Code

 

bash
claude mcp add icon-composer -- npx -y icon-composer-mcp
  [Image] Claude Desktop

 

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

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

 

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

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

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

  [Image] VS Code

 

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.

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

  [Image] Windsurf

 

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

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

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

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

  Other MCP clients

 

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

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

Or run the server directly:

bash
npx -y icon-composer-mcp
  CLI only (no MCP)

 

bash
npm install -g icon-composer-mcpicon-composer --help

How It Works

[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
    bash
    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

CommandDescription
createCreate a new .icon bundle from a foreground image
add-layerAdd a layer to an existing bundle
removeRemove a layer or group
inspectRead and display bundle contents
glassConfigure Liquid Glass effects on a group
appearanceSet dark/tinted mode overrides
fillSet background fill (solid, gradient, automatic, none)
positionSet layer/group scale and offset
fxToggle all glass effects on/off
previewExport a preview PNG (Liquid Glass or flat)
renderRender pixel-perfect Liquid Glass via ictool
export-marketingExport flat 1024x1024 PNG for App Store Connect (no alpha)
doctorCheck system setup and dependencies

Details

create — Create a new .icon bundle

 

bash
icon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]
OptionDefaultDescription
--bg-color <hex>requiredBackground color (e.g. "#0A66C2")
--bundle-name <name>AppIconBundle name (without .icon extension)
--dark-bg-color <hex>—Dark mode background color
--glyph-scale <n>1.0Glyph scale (1.0 = standard ~65% of icon area)
--specular / --no-speculartrueSpecular highlight
--shadow-kind <kind>layer-colorShadow type: neutral, layer-color, none
--shadow-opacity <n>0.5Shadow opacity (0–1)
--blur-material <n>—Blur material value (0–1)
--translucency-enabledfalseEnable translucency gradient
--translucency-value <n>0.4Translucency amount (0–1)

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

add-layer — Add a layer to an existing bundle

 

bash
icon-composer add-layer <bundle_path> <image_path> --name <name> [options]
OptionDefaultDescription
--name <name>requiredLayer name
--group-index <n>0Target group index
--create-groupfalseCreate a new group for this layer
--opacity <n>1.0Layer opacity (0–1)
--scale <n>1.0Layer scale
--offset-x <n>0X offset in points
--offset-y <n>0Y offset in points
--blend-mode <mode>normalBlend mode (e.g. multiply, screen, overlay)
--glass / --no-glasstrueParticipate in Liquid Glass effects

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

remove — Remove a layer or group

 

bash
icon-composer remove <bundle_path> --target <layer|group> --group-index <n> [--layer-index <n>]
inspect — Read and display bundle contents

 

bash
icon-composer inspect <bundle_path>

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

glass — Configure Liquid Glass effects

 

bash
icon-composer glass <bundle_path> [options]
OptionDescription
--group-index <n>Target group (default: 0)
--specular / --no-specularSpecular 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-enabledTranslucency 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
appearance — Set dark/tinted mode overrides

 

bash
icon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]
OptionDescription
--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-specularSpecular 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-enabledTranslucency toggle for this appearance
--translucency-value <n>Translucency amount (0–1) for this appearance
--hidden / --no-hiddenHidden 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
fill — Set background fill

 

bash
icon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]
OptionDescription
--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)
position — Set layer/group scale and offset

 

bash
icon-composer position <bundle_path> [options]
OptionDefaultDescription
--target <type>layerlayer or group
--group-index <n>0Group 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
fx — Toggle all glass effects

 

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

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

preview — Export a preview PNG

 

bash
icon-composer preview <bundle_path> <output_path> [options]
OptionDefaultDescription
--size <n>1024Output size in pixels
--appearance <mode>—dark or tinted
--flatfalseForce 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.0Zoom 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).

render — Render Liquid Glass via ictool

 

bash
icon-composer render <bundle_path> <output_path> [options]
OptionDefaultDescription
--platform <name>iOSiOS, macOS, or watchOS
--rendition <name>DefaultDefault, Dark, TintedLight, TintedDark, ClearLight, ClearDark
--width <n>1024Output width
--height <n>1024Output height
--scale <n>1Scale 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.

export-marketing — Export for App Store Connect

 

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

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

doctor — Check system setup

 

bash
icon-composer doctor

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


MCP Tools

ToolDescription
create_iconCreate a .icon bundle from a foreground image and background color
add_layer_to_iconAdd a new layer to an existing bundle
remove_layerRemove a layer or group, optionally clean up assets
read_iconInspect bundle manifest and assets
set_glass_effectsConfigure specular, blur, shadow, translucency
set_appearancesSet dark/tinted mode overrides
set_fillSet background fill
set_layer_positionAdjust layer scale and offset
toggle_fxEnable/disable all glass effects at once
export_previewRender a preview PNG
render_liquid_glassRender via Apple's ictool (requires Icon Composer)
export_marketingExport flat opaque PNG for App Store Connect

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

Details

create_icon

 

Create a .icon bundle from a foreground image.

ParameterTypeRequiredDefaultDescription
foreground_pathstringyes—Absolute path to PNG or SVG
output_dirstringyes—Output directory
bundle_namestringnoAppIconBundle name
bg_colorstringyes—Background hex color
dark_bg_colorstringno—Dark mode background color
glyph_scalenumberno1.0Glyph scale (0.1–2.0)
specularbooleannotrueSpecular highlight
shadow_kindenumnolayer-colorneutral, layer-color, none
shadow_opacitynumberno0.5Shadow opacity (0–1)
blur_materialnumberno—Blur amount (0–1)
translucency_enabledbooleannofalseEnable translucency
translucency_valuenumberno0.4Translucency amount (0–1)
add_layer_to_icon

 

add_layer_to_icon

Add a layer to an existing bundle.

ParameterTypeRequiredDefaultDescription
bundle_pathstringyes—Path to .icon bundle
image_pathstringyes—Path to image file
layer_namestringyes—Layer name
group_indexnumberno0Target group
create_groupbooleannofalseCreate new group
opacitynumberno1.0Layer opacity (0–1)
scalenumberno1.0Layer scale (0.1–2.0)
offset_xnumberno0X offset
offset_ynumberno0Y offset
blend_modeenumnonormalBlend mode
glassbooleannotrueGlass participation
remove_layer

 

remove_layer

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

ParameterTypeRequiredDefault
bundle_pathstringyes—
targetenumyes—
group_indexnumberyes—
layer_indexnumberno—
cleanup_assetsbooleannotrue
read_icon

 

read_icon

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

ParameterTypeRequired
bundle_pathstringyes
set_glass_effects

 

set_glass_effects

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

ParameterTypeDefaultDescription
bundle_pathstring—Path to bundle
group_indexnumber0Target group
specularboolean—Specular toggle
blur_materialnumber|null—Blur (0–1, null to disable)
shadow_kindenum—neutral, layer-color, none
shadow_opacitynumber—Shadow opacity (0–1)
translucency_enabledboolean—Translucency toggle
translucency_valuenumber—Translucency amount (0–1)
opacitynumber—Group opacity (0–1)
blend_modeenum—Blend mode
lightingenum—combined or individual
set_appearances

 

set_appearances

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

ParameterTypeRequiredDescription
bundle_pathstringyesPath to bundle
targetenumyesfill, group, or layer
appearanceenumyesdark or tinted
group_indexnumbernoGroup index (for target=group or target=layer)
layer_indexnumbernoLayer index within the group (required when target=layer)
bg_colorstringnoBackground color for this appearance (target=fill)
specularbooleannoSpecular for this appearance (target=group)
shadow_kindenumnoShadow type (target=group)
shadow_opacitynumbernoShadow opacity (target=group)
opacitynumbernoOpacity for this appearance (target=group or target=layer)
blur_materialnumber|nullnoBlur material for this appearance (target=group)
translucency_enabledbooleannoEnable translucency for this appearance (target=group)
translucency_valuenumbernoTranslucency amount for this appearance (target=group)
hiddenbooleannoHidden state for this appearance (target=group or target=layer)
blend_modeenumnoBlend mode for this appearance (target=layer)
fill_colorstringnoFill color hex for this appearance (target=layer)
position_scalenumbernoPosition scale for this appearance (0.05–3.0)
position_offset_xnumbernoPosition X offset for this appearance
position_offset_ynumbernoPosition Y offset for this appearance
set_fill

 

set_fill

Set background fill.

ParameterTypeRequiredDescription
bundle_pathstringyesPath to bundle
fill_typeenumyessolid, gradient, automatic, none
colorstringnoHex color (solid or gradient bottom)
color2stringnoGradient top color
gradient_anglenumbernoAngle in degrees (default: 0)
set_layer_position

 

set_layer_position

Adjust layer or group scale and offset.

ParameterTypeDefaultDescription
bundle_pathstring—Path to bundle
targetenumlayerlayer or group
group_indexnumber0Group index
layer_indexnumber—Layer index (for target=layer)
scalenumber—Scale (0.05–3.0)
offset_xnumber—X offset
offset_ynumber—Y offset
toggle_fx

 

toggle_fx

Enable or disable all glass effects on every group.

ParameterTypeRequired
bundle_pathstringyes
enabledbooleanyes
export_preview

 

export_preview

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

ParameterTypeDefaultDescription
bundle_pathstring—Path to bundle
output_pathstring—Output PNG path
sizenumber1024Output size (16–2048)
appearanceenum—dark or tinted
flatbooleanfalseForce flat rendering
canvas_bgenum—Preset background
apple_presetenum—Apple wallpaper preset
canvas_bg_colorstring—Custom background hex
canvas_bg_imagestring—Background image path
zoomnumber1.0Zoom level (0.1–3.0)
return_imagebooleantrueReturn rendered image inline as base64
render_liquid_glass

 

render_liquid_glass

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

ParameterTypeDefaultDescription
bundle_pathstring—Path to bundle
output_pathstring—Output PNG path
platformenumiOSiOS, macOS, watchOS
renditionenumDefaultDefault, Dark, TintedLight, TintedDark, ClearLight, ClearDark
widthnumber1024Output width (16–2048)
heightnumber1024Output height (16–2048)
scalenumber1Scale factor (1–3)
light_anglenumber—Light angle (0–360)
tint_colornumber—Tint hue (0–1)
tint_strengthnumber—Tint strength (0–1)
Canvas options——Same as export_preview
return_imagebooleantrueReturn rendered image inline as base64
export_marketing

 

export_marketing

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

ParameterTypeDefaultDescription
bundle_pathstring—Path to bundle
output_pathstring—Output PNG path
sizenumber1024Output size (16–2048)
return_imagebooleantrueReturn rendered image inline as base64

MCP Prompts

PromptParametersDescription
create-app-iconimage_path, output_dir, brand_color, dark_color?Guided workflow: create icon from a logo, preview, iterate, export
add-dark-modebundle_path, dark_colorAdd dark mode to an existing icon with before/after preview
export-for-app-storebundle_path, output_dirExport marketing PNG + preview for App Store submission

Example Workflows

Create a branded icon

bash
# Create with brand coloricon-composer create logo.svg ./out --bg-color "#0A66C2"
# Add dark modeicon-composer appearance ./out/AppIcon.icon --target fill --appearance dark --bg-color "#0D1B2A"
# Configure glass effectsicon-composer glass ./out/AppIcon.icon --specular --shadow-kind layer-color --blur-material 0.3
# Previewicon-composer preview ./out/AppIcon.icon preview.png

Export for App Store

bash
# 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

bash
# Create base iconicon-composer create background.svg ./out --bg-color "#1C1C2E"
# Add foreground layersicon-composer add-layer ./out/AppIcon.icon glyph.svg --name glyph --opacity 0.8icon-composer add-layer ./out/AppIcon.icon badge.svg --name badge --create-group
# Configure glass per groupicon-composer glass ./out/AppIcon.icon --group-index 0 --specular --blur-material 0.3icon-composer glass ./out/AppIcon.icon --group-index 1 --specular --shadow-kind neutral
# Render Liquid Glassicon-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

bash
# Install dependenciesbun install
# Run testsbun test              # 175 unit testsnpm run test:mcp      # 16 MCP integration tests
# Buildbun run build
# Visual test gallerybun src/cli.ts visual-test --out ./gallery

Source: README.md at commit e7d2b32

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts