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 分