Icon Composer Mcp

io.github.ethbak由 GitHub 帳號 ethbak 發布v1.1.0更新於 Oct 24, 2026

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

已驗證STDIO僅桌面開發者工具媒體與設計

概覽

AI 產生的概覽

建立與編輯帶有 Liquid Glass 效果的 Apple .icon 圖示套件,並匯出預覽圖與 App Store 行銷圖示。

可以做什麼
提供 12 個 MCP 工具與 3 個引導式提示,可從 PNG 或 SVG 圖形建立 Apple .icon 圖示套件。工具能建立套件、新增或移除圖層與群組、設定背景填色、配置高光、模糊、陰影與半透明等 Liquid Glass 效果,並定義深色或色調外觀覆寫。它也能匯出預覽 PNG、透過 Apple 的 ictool 算繪像素級精確的 Liquid Glass,以及匯出供 App Store Connect 使用的扁平 1024x1024 行銷圖示。
適用情境
適合需要產生或反覆調整 iOS 26+ 應用程式圖示、標誌或品牌圖示集的場合,包括深色模式變體與 App Store 行銷素材。最適合想取得 Liquid Glass 算繪的 macOS 使用者;扁平預覽與套件編輯在其他平台也能使用。
執行需求
透過 npx icon-composer-mcp 以 stdio 在本機執行,需要 Node.js 18+。Liquid Glass 算繪需要 macOS 並安裝 Apple 的 Icon Composer.app;扁平預覽、套件建立與編輯以及行銷匯出可在任何平台使用。未宣告需要帳號、API 金鑰或環境變數。
安裝前請注意
工具會寫入你指定的路徑,包括建立、修改與刪除 .icon 套件及其資源,並可將算繪影像以 base64 內嵌回傳。算繪依賴 Apple 的 ictool 與 Icon Composer.app,需另行安裝。本專案聲明與 Apple 無關。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Icon Composer Mcp,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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

  [圖片] Claude Code

 

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

 

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

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

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

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.

  [圖片] 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

來源:README.md,提交 e7d2b32

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.1.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分