Icon Composer MCP

Icon Composer MCP

MCP server for creating Apple .icon bundles with Liquid Glass effects (iOS 26+). 12 tools for programmatic icon creation, glass effect tuning, dark mode, and App Store export.

Category
访问服务器

README

<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>  <img src="https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-svg/icons/claudecode-color.svg" width="16" height="16"> <b>Claude Code</b></summary>

 

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

</details>

<details> <summary>  <img src="https://cdn.simpleicons.org/claude/D97757" width="16" height="16"> <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>  <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> <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>  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vscode/vscode-original.svg" width="16" height="16"> <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>  <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> <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>  <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>  <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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议,是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器,它使大型语言模型能够通过结构化的可访问性快照与网页进行交互,而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具,可以从自然语言描述生成现代化的用户界面组件,并与流行的集成开发环境(IDE)集成,从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互,从而促进营销洞察和受众数据的提取和分析,包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具,连接你所有喜爱的工具:Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外,还可以将任何内容(从 Slack 到 Gmail 再到播客订阅源)导入到 Graphlit 项目中,然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器,集成了 Kagi 搜索功能和 Claude AI,使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议(MCP)服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选