io.github.ethbak/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 .

---

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 Code

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

Claude Desktop

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

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

Cursor

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.

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.

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

Windsurf

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.

Other MCP clients

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

CLI only (no 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

Details

create — Create a new .icon bundle

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

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

add-layer — Add a layer to an existing bundle

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

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

remove — Remove a layer or group

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

inspect — Read and display bundle contents

icon-composer inspect <bundle_path>

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

glass — Configure Liquid Glass effects

icon-composer glass <bundle_path> [options]

appearance — Set dark/tinted mode overrides

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

fill — Set background fill

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

position — Set layer/group scale and offset

icon-composer position <bundle_path> [options]

fx — Toggle all glass effects

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

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

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

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

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

export-marketing — Export for App Store Connect

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

icon-composer doctor

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

---

MCP Tools

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

Details

create_icon

Create a .icon bundle from a foreground image.

add_layer_to_icon

add_layer_to_icon

Add a layer to an existing bundle.

remove_layer

remove_layer

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

read_icon

read_icon

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

set_glass_effects

set_glass_effects

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

set_appearances

set_appearances

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

set_fill

set_fill

Set background fill.

set_layer_position

set_layer_position

Adjust layer or group scale and offset.

toggle_fx

toggle_fx

Enable or disable all glass effects on every group.

export_preview

export_preview

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

render_liquid_glass

render_liquid_glass

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

export_marketing

export_marketing

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

---

MCP Prompts

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