Icon Composer MCP
The Icon Composer MCP server enables programmatic creation, modification, and export of Apple .icon bundles with Liquid Glass effects (iOS 26+).
Create
.iconbundles – Generate new icon bundles from PNG or SVG images with configurable background colors, glyph scaling, and Liquid Glass effectsManage layers – Add image layers with control over opacity, scale, offset, blend mode, and glass participation; remove individual layers or entire groups with optional orphaned asset cleanup
Configure Liquid Glass effects – Adjust specular highlights, blur material, shadow type/opacity, translucency, group opacity, blend mode, and lighting mode on layer groups
Set appearance overrides – Define dark mode or tinted mode variations for background fill, group glass properties, or individual layer properties (visibility, blend mode, fill color, positioning)
Set background fill – Apply solid colors, gradients (with angle), automatic, or no fill to the icon background
Adjust layer/group position – Control scale (0.05–3.0) and X/Y offset for individual layers or groups
Toggle all glass effects – Enable or disable specular, shadow, blur, and translucency across all groups at once
Inspect bundles – Read the full manifest JSON and list all assets with sizes for any existing
.iconbundleExport preview PNG – Render a preview with Liquid Glass (via Apple's
ictool) or flat composite, supporting canvas backgrounds, zoom, and appearance modesRender pixel-perfect Liquid Glass – Use Apple's
ictoolto produce exact renders for iOS, macOS, or watchOS across renditions (Default, Dark, Tinted, Clear) with light angle and tint controls (requires macOS + Icon Composer.app)Export for App Store Connect – Generate a flat, opaque 1024×1024 PNG with no alpha or glass effects, suitable for App Store marketing submission
AI agent workflows – Includes specialized prompts to guide AI agents through common tasks like creating an app icon, adding dark mode, and preparing for App Store submission
Creates .icon bundles using Apple's Icon Composer tool and ictool for rendering Liquid Glass effects, specular highlights, and translucency. Generates platform-compliant assets for iOS and macOS applications using Apple's design specifications.
Exports marketing assets for App Store Connect, including flat 1024x1024 PNGs without alpha channels required for App Store publishing, and generates preview renders suitable for app store listings.
Generates icon bundles specifically designed for iOS 26+ with full Liquid Glass support including specular highlights, blur materials, shadows, and translucency effects. Supports dark mode and tinted appearance variants for iOS devices.
Creates icon bundles compatible with macOS applications and leverages macOS-specific rendering capabilities through Apple's ictool for pixel-perfect Liquid Glass effects. Supports platform-specific features like dark mode appearance variants.
Produces .icon bundles that integrate directly with Xcode projects for iOS and macOS app development, generating the required manifest JSON and asset structures that Xcode recognizes for app icon management.
Demo
Related MCP server: XcodeBuildMCP
Key Features
Create
.iconbundles programmatically from PNG or SVG glyphsFull 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 --helpHow It Works
Provide a glyph — any PNG or SVG logo/image
Create a
.iconbundle — sets background fill, layer scale, and glass effectsApple's ictool renders Liquid Glass — specular highlights, shadows, depth, and translucency
Export — preview PNGs, App Store marketing icon, or the
.iconbundle for Xcode
Requirements
Node.js 18+
macOS with Icon Composer for Liquid Glass rendering
brew install --cask icon-composerFlat 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 a new |
| Add a layer to an existing bundle |
| Remove a layer or group |
| Read and display bundle contents |
| Configure Liquid Glass effects on a group |
| Set dark/tinted mode overrides |
| Set background fill (solid, gradient, automatic, none) |
| Set layer/group scale and offset |
| Toggle all glass effects on/off |
| Export a preview PNG (Liquid Glass or flat) |
| Render pixel-perfect Liquid Glass via ictool |
| Export flat 1024x1024 PNG for App Store Connect (no alpha) |
| Check system setup and dependencies |
Details
icon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]Option | Default | Description |
| required | Background color (e.g. |
|
| Bundle name (without |
| — | Dark mode background color |
|
| Glyph scale (1.0 = standard ~65% of icon area) |
|
| Specular highlight |
|
| Shadow type: |
|
| Shadow opacity (0–1) |
| — | Blur material value (0–1) |
|
| Enable translucency gradient |
|
| 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 |
| required | Layer name |
|
| Target group index |
|
| Create a new group for this layer |
|
| Layer opacity (0–1) |
|
| Layer scale |
|
| X offset in points |
|
| Y offset in points |
|
| Blend mode (e.g. |
|
| 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 |
| Target group (default: |
| Specular highlight |
| Blur amount (0–1) |
|
|
| Shadow opacity (0–1) |
| Translucency toggle |
| Translucency amount (0–1) |
| Group opacity (0–1) |
| Group blend mode |
|
|
icon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]Option | Description |
|
|
|
|
| Group index (for |
| Layer index within the group (required when |
| Background color for this appearance |
| Specular for this appearance |
| Shadow type for this appearance |
| Shadow opacity for this appearance |
| Opacity for this appearance |
| Blur material value (0–1) for this appearance |
| Translucency toggle for this appearance |
| Translucency amount (0–1) for this appearance |
| Hidden state for this appearance |
| Blend mode for this appearance (target=layer) |
| Fill color for this appearance (target=layer) |
| Position scale for this appearance |
| Position X offset for this appearance |
| Position Y offset for this appearance |
icon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]Option | Description |
|
|
| Primary color (for solid or gradient bottom) |
| Secondary color (gradient top) |
| Gradient angle in degrees (default: |
icon-composer position <bundle_path> [options]Option | Default | Description |
|
|
|
|
| Group index |
| — | Layer index (required for |
| — | Scale factor (0.05–3.0) |
| — | X offset in points |
| — | Y offset in points |
icon-composer fx <bundle_path> --enable|--disableEnables or disables specular, shadow, blur, and translucency on every group at once.
icon-composer preview <bundle_path> <output_path> [options]Option | Default | Description |
|
| Output size in pixels |
| — |
|
|
| Force flat rendering (skip Liquid Glass) |
| — |
|
| — | Apple wallpaper: |
| — | Custom background color |
| — | Custom background image |
|
| 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 |
|
|
|
|
|
|
|
| Output width |
|
| Output height |
|
| Scale factor (1x, 2x, 3x) |
| — | Light angle (0–360) |
| — | Tint hue (0–1) |
| — | Tint strength (0–1) |
Canvas options | — | Same as |
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 doctorOutput: Reports Node version, platform, ictool path and version. Prints install instructions if Icon Composer is missing.
MCP Tools
Tool | Description |
| Create a |
| Add a new layer to an existing bundle |
| Remove a layer or group, optionally clean up assets |
| Inspect bundle manifest and assets |
| Configure specular, blur, shadow, translucency |
| Set dark/tinted mode overrides |
| Set background fill |
| Adjust layer scale and offset |
| Enable/disable all glass effects at once |
| Render a preview PNG |
| Render via Apple's ictool (requires Icon Composer) |
| 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 |
| string | yes | — | Absolute path to PNG or SVG |
| string | yes | — | Output directory |
| string | no |
| Bundle name |
| string | yes | — | Background hex color |
| string | no | — | Dark mode background color |
| number | no |
| Glyph scale (0.1–2.0) |
| boolean | no |
| Specular highlight |
| enum | no |
|
|
| number | no |
| Shadow opacity (0–1) |
| number | no | — | Blur amount (0–1) |
| boolean | no |
| Enable translucency |
| number | no |
| Translucency amount (0–1) |
add_layer_to_icon
Add a layer to an existing bundle.
Parameter | Type | Required | Default | Description |
| string | yes | — | Path to |
| string | yes | — | Path to image file |
| string | yes | — | Layer name |
| number | no |
| Target group |
| boolean | no |
| Create new group |
| number | no |
| Layer opacity (0–1) |
| number | no |
| Layer scale (0.1–2.0) |
| number | no |
| X offset |
| number | no |
| Y offset |
| enum | no |
| Blend mode |
| boolean | no |
| Glass participation |
remove_layer
Remove a layer or group. layer_index required when target=layer.
Parameter | Type | Required | Default | |
| string | yes | — | |
| enum | yes | — |
|
| number | yes | — | |
| number | no | — | |
| boolean | no |
|
read_icon
Inspect a bundle. Returns full manifest JSON and asset list with sizes.
Parameter | Type | Required |
| 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 |
| string | — | Path to bundle |
| number |
| Target group |
| boolean | — | Specular toggle |
| number|null | — | Blur (0–1, null to disable) |
| enum | — |
|
| number | — | Shadow opacity (0–1) |
| boolean | — | Translucency toggle |
| number | — | Translucency amount (0–1) |
| number | — | Group opacity (0–1) |
| enum | — | Blend mode |
| enum | — |
|
set_appearances
Set dark/tinted overrides for background fill, group effects, or individual layer properties.
Parameter | Type | Required | Description |
| string | yes | Path to bundle |
| enum | yes |
|
| enum | yes |
|
| number | no | Group index (for |
| number | no | Layer index within the group (required when |
| string | no | Background color for this appearance (target=fill) |
| boolean | no | Specular for this appearance (target=group) |
| enum | no | Shadow type (target=group) |
| number | no | Shadow opacity (target=group) |
| number | no | Opacity for this appearance (target=group or target=layer) |
| number|null | no | Blur material for this appearance (target=group) |
| boolean | no | Enable translucency for this appearance (target=group) |
| number | no | Translucency amount for this appearance (target=group) |
| boolean | no | Hidden state for this appearance (target=group or target=layer) |
| enum | no | Blend mode for this appearance (target=layer) |
| string | no | Fill color hex for this appearance (target=layer) |
| number | no | Position scale for this appearance (0.05–3.0) |
| number | no | Position X offset for this appearance |
| number | no | Position Y offset for this appearance |
set_fill
Set background fill.
Parameter | Type | Required | Description |
| string | yes | Path to bundle |
| enum | yes |
|
| string | no | Hex color (solid or gradient bottom) |
| string | no | Gradient top color |
| number | no | Angle in degrees (default: |
set_layer_position
Adjust layer or group scale and offset.
Parameter | Type | Default | Description |
| string | — | Path to bundle |
| enum |
|
|
| number |
| Group index |
| number | — | Layer index (for |
| number | — | Scale (0.05–3.0) |
| number | — | X offset |
| number | — | Y offset |
toggle_fx
Enable or disable all glass effects on every group.
Parameter | Type | Required |
| string | yes |
| boolean | yes |
export_preview
Render a preview PNG. Uses Liquid Glass by default, falls back to flat.
Parameter | Type | Default | Description |
| string | — | Path to bundle |
| string | — | Output PNG path |
| number |
| Output size (16–2048) |
| enum | — |
|
| boolean |
| Force flat rendering |
| enum | — | Preset background |
| enum | — | Apple wallpaper preset |
| string | — | Custom background hex |
| string | — | Background image path |
| number |
| Zoom level (0.1–3.0) |
| boolean |
| Return rendered image inline as base64 |
render_liquid_glass
Pixel-perfect Liquid Glass via Apple's ictool. Requires Icon Composer.app.
Parameter | Type | Default | Description |
| string | — | Path to bundle |
| string | — | Output PNG path |
| enum |
|
|
| enum |
|
|
| number |
| Output width (16–2048) |
| number |
| Output height (16–2048) |
| number |
| Scale factor (1–3) |
| number | — | Light angle (0–360) |
| number | — | Tint hue (0–1) |
| number | — | Tint strength (0–1) |
Canvas options | — | — | Same as |
| boolean |
| Return rendered image inline as base64 |
export_marketing
Flat marketing PNG for App Store Connect. No glass effects, no alpha channel.
Parameter | Type | Default | Description |
| string | — | Path to bundle |
| string | — | Output PNG path |
| number |
| Output size (16–2048) |
| boolean |
| Return rendered image inline as base64 |
MCP Prompts
Prompt | Parameters | Description |
|
| Guided workflow: create icon from a logo, preview, iterate, export |
|
| Add dark mode to an existing icon with before/after preview |
|
| 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.pngExport 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 catalogMulti-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.pngLimitations
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 ./galleryLatest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ethbak/icon-composer-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server