mcpField
I
icon-composer-mcp

icon-composer-mcp

本地服务
github.com/ethbak媒体与设计624 周前更新

关于 icon-composer-mcp

icon-composer-mcp 是一个命令行工具与 MCP 服务,用于创建带有 Liquid Glass 效果的 Apple .icon 包,适用于 iOS 26 及以上版本。面向需要为应用生成图标与标志的开发者,也可由 AI Agent 调用。项目与 Apple 无关联。

主要功能

  1. 01从 PNG 或 SVG 图形创建 .icon 包
  2. 02配置高光、模糊、阴影与透光效果
  3. 03支持深色模式与外观变体
  4. 04提供 12 个 MCP 工具与 3 个工作流提示词
  5. 05提供 doctor 命令检查环境

适用场景

  1. 01为 iOS 应用生成带 Liquid Glass 效果的图标
  2. 02导出 App Store Connect 所需的无透明通道营销图标
  3. 03通过 AI Agent 批量调整图标图层与填充

MCP 相关

该服务以 stdio 方式运行,向 MCP 客户端提供创建、编辑、预览和导出 .icon 包的 12 个工具,并附带工作流提示词。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"ethbak-icon-composer": {
"command": "npx",
"args": [
"-y",
"icon-composer-mcp"
]
}
}
}
启动命令npx -y icon-composer-mcp

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npmicon-composer-mcp1.1.0

工具

12

收录的工具列表 · 更新于 2 周前

参数类型必填说明
bg_colorstring是十六进制格式的背景颜色(例如 #0A66C2)
specularboolean否启用镜面高光(Liquid Glass)
output_dirstring是写入 .icon 包的目录
bundle_namestring否.icon 包的名称(不含扩展名)
glyph_scalenumber否前景字形的缩放比例(0.1-2.0,默认值 1.0 在 Icon Composer 中填充图标区域的约 65%)
shadow_kindenum否阴影类型neutral | layer-color | none
split_layersboolean否将多形状 SVG 拆分为独立的玻璃图层(每个形状都应用独立的玻璃效果)
blur_materialnumber否Liquid Glass 模糊量(0-1,省略则禁用)
dark_bg_colorstring否十六进制格式的深色模式背景颜色
shadow_opacitynumber否阴影不透明度
foreground_pathstring是前景图像的绝对路径(PNG 或 SVG)
translucency_valuenumber否半透明度(0-1)
translucency_enabledboolean否启用半透明渐变

详细介绍

icon-composer-mcp

Icon Composer MCP

用于创建带有 Liquid Glass 效果(iOS 26+)的图像、图标和徽标的命令行工具和 MCP 服务。与 Apple  无关。

npm 版本 许可证 平台 兼容 MCP Glama 评分


演示

演示

主要功能

  • 以编程方式从 PNG 或 SVG 字形创建 .icon 资源包
  • 全面支持 Liquid Glass:高光、模糊材质、阴影、半透明效果
  • 深色模式 + 外观变体,支持按外观进行填充特化
  • 为 AI Agent 做好准备:12 个 MCP 工具 + 3 个内置说明的工作流提示词

安装

  README 配图 Claude Code

 

claude mcp add icon-composer -- npx -y icon-composer-mcp
  README 配图 Claude Desktop

 

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

 

在项目根目录的 .cursor/mcp.json 中添加(或在全局配置文件 ~/.cursor/mcp.json 中添加):

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

服务会显示在 Cursor Settings > MCP Servers 中。无需重启。

  README 配图 VS Code

 

在项目根目录的 .vscode/mcp.json 中添加(或打开 Command Palette > MCP: Open User Configuration 进行全局配置):

注意: VS Code 使用 "servers"(而非 "mcpServers"),并且需要 "type" 字段。

{
  "servers": {
    "icon-composer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}

编辑器中会显示启动/停止/重启按钮。首次启动时会提示确认信任。

  README 配图 Windsurf

 

首先,在 Windsurf Settings > Cascade > Model Context Protocol (MCP) 中启用 MCP。

然后添加到 ~/.codeium/windsurf/mcp_config.json:

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

点击 Windsurf 设置中的刷新按钮以加载服务。

  其他 MCP 客户端

 

该服务使用 stdio 传输。大多数 MCP 客户端使用以下配置格式:

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

或者直接运行服务:

npx -y icon-composer-mcp
  仅使用 CLI(无 MCP)

 

npm install -g icon-composer-mcp
icon-composer --help

工作原理

工作原理

  1. 提供一个图形 — 任意 PNG 或 SVG 徽标/图像
  2. 创建 .icon 捆绑包 — 设置背景填充、图层缩放和玻璃效果
  3. Apple 的 ictool 渲染 Liquid Glass — 高光、阴影、深度和半透明效果
  4. 导出 — 预览 PNG、App Store 营销图标,或用于 Xcode 的 .icon 捆绑包

要求

  • Node.js 18+
  • macOS,并安装 Icon Composer 以渲染 Liquid Glass
    brew install --cask icon-composer
    
  • 扁平预览、捆绑包创建/编辑和营销导出可在任何平台上运行,无需 Icon Composer

运行 icon-composer doctor 检查设置。

CLI 命令

命令描述
create从前景图像创建新的 .icon bundle
add-layer向现有 bundle 添加图层
remove移除图层或组
inspect读取并显示 bundle 内容
glass配置组的 Liquid Glass 效果
appearance设置深色/着色模式覆盖项
fill设置背景填充(纯色、渐变、自动、无)
position设置图层/组的缩放和偏移
fx开启/关闭所有玻璃效果
preview导出预览 PNG(Liquid Glass 或平面效果)
render通过 ictool 渲染像素级精准的 Liquid Glass
export-marketing导出用于 App Store Connect 的平面 1024x1024 PNG(无 alpha 通道)
doctor检查系统设置和依赖项
详细信息
create — 创建新的 .icon bundle

 

icon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]
选项默认值描述
--bg-color <hex>必填背景颜色(例如 "#0A66C2")
--bundle-name <name>AppIconBundle 名称(不含 .icon 扩展名)
--dark-bg-color <hex>—深色模式背景颜色
--glyph-scale <n>1.0字形缩放比例(1.0 = 标准尺寸,约占图标区域的 65%)
--specular / --no-speculartrue镜面高光
--shadow-kind <kind>layer-color阴影类型:neutral、layer-color、none
--shadow-opacity <n>0.5阴影不透明度(0–1)
--blur-material <n>—模糊材质值(0–1)
--translucency-enabledfalse启用半透明渐变
--translucency-value <n>0.4半透明程度(0–1)

**输出:**创建 <output_dir>/<bundle_name>.icon/,其中包含 icon.json 清单文件和 Assets/ 目录。

add-layer — 向现有 bundle 添加图层

 

icon-composer add-layer <bundle_path> <image_path> --name <name> [options]
选项默认值描述
--name <name>必填图层名称
--group-index <n>0目标组索引
--create-groupfalse为此图层创建新组
--opacity <n>1.0图层不透明度(0–1)
--scale <n>1.0图层缩放比例
--offset-x <n>0X 轴偏移量(点)
--offset-y <n>0Y 轴偏移量(点)
--blend-mode <mode>normal混合模式(例如 multiply、screen、overlay)
--glass / --no-glasstrue是否参与 Liquid Glass 效果

支持的格式:.png、.jpg、.jpeg、.svg、.webp、.heic、.heif

remove — 移除图层或组

 

icon-composer remove <bundle_path> --target <layer|group> --group-index <n> [--layer-index <n>]
inspect — 读取并显示 bundle 内容

 

icon-composer inspect <bundle_path>

**输出:**打印完整的清单 JSON,并列出所有资源及其大小。

glass — 配置 Liquid Glass 效果

 

icon-composer glass <bundle_path> [options]
选项描述
--group-index <n>目标组(默认:0)
--specular / --no-specular镜面高光
--blur-material <n>模糊程度(0–1)
--shadow-kind <kind>neutral、layer-color 或 none
--shadow-opacity <n>阴影不透明度(0–1)
--translucency-enabled / --no-translucency-enabled半透明开关
--translucency-value <n>半透明程度(0–1)
--opacity <n>组不透明度(0–1)
--blend-mode <mode>组混合模式
--lighting <type>combined 或 individual
appearance — 设置深色/着色模式覆盖项

 

icon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]
选项说明
--target <type>fill(背景颜色)、group(玻璃效果)或 layer(单个图层)
--appearance <mode>dark 或 tinted
--group-index <n>组索引(用于 target=group 或 target=layer)
--layer-index <n>组内的图层索引(target=layer 时必填)
--bg-color <hex>此外观的背景颜色
--specular / --no-specular此外观的镜面效果
--shadow-kind <kind>此外观的阴影类型
--shadow-opacity <n>此外观的阴影不透明度
--opacity <n>此外观的不透明度
--blur-material <n>此外观的模糊材质值(0–1)
--translucency-enabled / --no-translucency-enabled此外观的半透明效果开关
--translucency-value <n>此外观的半透明程度(0–1)
--hidden / --no-hidden此外观的隐藏状态
--blend-mode <mode>此外观的混合模式(target=layer)
--fill-color <hex>此外观的填充颜色(target=layer)
--position-scale <n>此外观的位置缩放比例
--position-offset-x <n>此外观的 X 轴位置偏移
--position-offset-y <n>此外观的 Y 轴位置偏移
fill — 设置背景填充

 

icon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]
选项说明
--type <type>solid、gradient、automatic 或 none
--color <hex>主颜色(用于纯色或渐变底部)
--color2 <hex>次要颜色(渐变顶部)
--gradient-angle <n>渐变角度(度,默认值:0)
position — 设置图层/组的缩放和偏移

 

icon-composer position <bundle_path> [options]
选项默认值说明
--target <type>layerlayer 或 group
--group-index <n>0组索引
--layer-index <n>—图层索引(--target layer 时必填)
--scale <n>—缩放系数(0.05–3.0)
--offset-x <n>—X 轴偏移(点)
--offset-y <n>—Y 轴偏移(点)
fx — 切换所有玻璃效果

 

icon-composer fx <bundle_path> --enable|--disable

一次性启用或禁用每个组的镜面效果、阴影、模糊和半透明效果。

preview — 导出预览 PNG

 

icon-composer preview <bundle_path> <output_path> [options]
选项默认值说明
--size <n>1024输出尺寸(像素)
--appearance <mode>—dark 或 tinted
--flatfalse强制使用平面渲染(跳过 Liquid Glass)
--canvas-bg <preset>—light、dark、checkerboard、homescreen-light、homescreen-dark
--apple-preset <name>—Apple 壁纸:sine-purple-orange、sine-gasflame、sine-magenta、sine-green-yellow、sine-purple-orange-black、sine-gray
--canvas-bg-color <hex>—自定义背景颜色
--canvas-bg-image <path>—自定义背景图片
--zoom <n>1.0缩放级别(图标大小相对于画布的比例)

输出: PNG 文件。默认使用 Liquid Glass 渲染(如果未安装 Icon Composer,则回退到平面渲染)。

render — 通过 ictool 渲染 Liquid Glass

 

icon-composer render <bundle_path> <output_path> [options]
选项默认值描述
--platform <name>iOSiOS、macOS 或 watchOS
--rendition <name>DefaultDefault、Dark、TintedLight、TintedDark、ClearLight、ClearDark
--width <n>1024输出宽度
--height <n>1024输出高度
--scale <n>1缩放系数(1x、2x、3x)
--light-angle <n>—光照角度(0–360)
--tint-color <n>—色调色相(0–1)
--tint-strength <n>—色调强度(0–1)
画布选项—与 preview 相同

需要: 已安装 Icon Composer.app。若未安装,则返回包含安装说明的错误。

export-marketing — 为 App Store Connect 导出

 

icon-composer export-marketing <bundle_path> <output_path> [--size <n>]

输出: 不含 Alpha 通道的扁平 PNG(避免被 ITMS-90717 拒绝)。默认尺寸为 1024x1024。

doctor — 检查系统设置

 

icon-composer doctor

输出: 报告 Node 版本、平台、ictool 路径和版本。若缺少 Icon Composer,则显示安装说明。


MCP 工具

工具描述
create_icon根据前景图像和背景色创建 .icon 包
add_layer_to_icon向现有包添加新图层
remove_layer移除图层或组,并可选择清理资源
read_icon检查包清单和资源
set_glass_effects配置高光、模糊、阴影和半透明效果
set_appearances设置深色/色调模式覆盖项
set_fill设置背景填充
set_layer_position调整图层缩放和偏移
toggle_fx一次性启用/禁用所有玻璃效果
export_preview渲染预览 PNG
render_liquid_glass通过 Apple 的 ictool 渲染(需要 Icon Composer)
export_marketing导出适用于 App Store Connect 的扁平不透明 PNG

所有工具均返回 { content: [{ type: "text", text: "..." }], isError?: true }。

详情
create_icon

 

根据前景图像创建 .icon 包。

参数类型必填默认值描述
foreground_pathstring是—PNG 或 SVG 的绝对路径
output_dirstring是—输出目录
bundle_namestring否AppIcon包名称
bg_colorstring是—背景十六进制颜色
dark_bg_colorstring否—深色模式背景色
glyph_scalenumber否1.0字形缩放(0.1–2.0)
specularboolean否true镜面高光
shadow_kindenum否layer-colorneutral、layer-color、none
shadow_opacitynumber否0.5阴影不透明度(0–1)
blur_materialnumber否—模糊量(0–1)
translucency_enabledboolean否false启用半透明效果
translucency_valuenumber否0.4半透明量(0–1)
add_layer_to_icon

 

add_layer_to_icon

向现有资源包添加图层。

参数类型必填默认值描述
bundle_pathstring是—.icon 资源包的路径
image_pathstring是—图像文件的路径
layer_namestring是—图层名称
group_indexnumber否0目标组
create_groupboolean否false创建新组
opacitynumber否1.0图层不透明度(0–1)
scalenumber否1.0图层缩放比例(0.1–2.0)
offset_xnumber否0X 偏移量
offset_ynumber否0Y 偏移量
blend_modeenum否normal混合模式
glassboolean否true是否参与玻璃效果
remove_layer

 

remove_layer

移除图层或组。当 target=layer 时,必须提供 layer_index。

参数类型必填默认值
bundle_pathstring是—
targetenum是—
group_indexnumber是—
layer_indexnumber否—
cleanup_assetsboolean否true
read_icon

 

read_icon

检查资源包。返回完整的清单 JSON,以及包含大小信息的资源列表。

参数类型必填
bundle_pathstring是
set_glass_effects

 

set_glass_effects

配置组上的 Liquid Glass。所有效果参数均为可选项,仅更改已提供的值。

参数类型默认值描述
bundle_pathstring—资源包的路径
group_indexnumber0目标组
specularboolean—镜面效果开关
blur_materialnumber|null—模糊(0–1,设为 null 可禁用)
shadow_kindenum—neutral、layer-color、none
shadow_opacitynumber—阴影不透明度(0–1)
translucency_enabledboolean—半透明效果开关
translucency_valuenumber—半透明程度(0–1)
opacitynumber—组不透明度(0–1)
blend_modeenum—混合模式
lightingenum—combined 或 individual
set_appearances

 

set_appearances

为背景填充、组效果或单个图层属性设置深色/着色覆盖效果。

参数类型必填描述
bundle_pathstring是Bundle 路径
targetenum是fill、group 或 layer
appearanceenum是dark 或 tinted
group_indexnumber否组索引(用于 target=group 或 target=layer)
layer_indexnumber否组内的图层索引(target=layer 时必填)
bg_colorstring否此外观的背景颜色(target=fill)
specularboolean否此外观的镜面效果(target=group)
shadow_kindenum否阴影类型(target=group)
shadow_opacitynumber否阴影不透明度(target=group)
opacitynumber否此外观的不透明度(用于 target=group 或 target=layer)
blur_materialnumber|null否此外观的模糊材质(target=group)
translucency_enabledboolean否为此外观启用半透明效果(target=group)
translucency_valuenumber否此外观的半透明程度(target=group)
hiddenboolean否此外观的隐藏状态(用于 target=group 或 target=layer)
blend_modeenum否混合模式(target=layer)
fill_colorstring否此外观的填充颜色十六进制值(target=layer)
position_scalenumber否位置缩放(0.05–3.0)
position_offset_xnumber否此外观的位置 X 偏移
position_offset_ynumber否此外观的位置 Y 偏移
set_fill

 

set_fill

设置背景填充。

参数类型必填描述
bundle_pathstring是Bundle 路径
fill_typeenum是solid、gradient、automatic、none
colorstring否十六进制颜色(纯色或渐变底部颜色)
color2string否渐变顶部颜色
gradient_anglenumber否角度(以度为单位,默认值:0)
set_layer_position

 

set_layer_position

调整图层或组的缩放和偏移。

参数类型默认值描述
bundle_pathstring—Bundle 路径
targetenumlayerlayer 或 group
group_indexnumber0组索引
layer_indexnumber—图层索引(用于 target=layer)
scalenumber—缩放(0.05–3.0)
offset_xnumber—X 偏移
offset_ynumber—Y 偏移
toggle_fx

 

toggle_fx

启用或禁用每个组上的所有玻璃效果。

参数类型必填
bundle_pathstring是
enabledboolean是
export_preview

 

export_preview

渲染预览 PNG。默认使用 Liquid Glass,失败时回退到平面渲染。

参数类型默认值说明
bundle_pathstring—Bundle 路径
output_pathstring—输出 PNG 路径
sizenumber1024输出尺寸(16–2048)
appearanceenum—dark 或 tinted
flatbooleanfalse强制使用平面渲染
canvas_bgenum—预设背景
apple_presetenum—Apple 壁纸预设
canvas_bg_colorstring—自定义背景十六进制颜色
canvas_bg_imagestring—背景图片路径
zoomnumber1.0缩放级别(0.1–3.0)
return_imagebooleantrue以 base64 内联形式返回渲染后的图片
render_liquid_glass

 

render_liquid_glass

通过 Apple 的 ictool 实现像素级精准的 Liquid Glass 渲染。需要 Icon Composer.app。

参数类型默认值说明
bundle_pathstring—Bundle 路径
output_pathstring—输出 PNG 路径
platformenumiOSiOS、macOS、watchOS
renditionenumDefaultDefault、Dark、TintedLight、TintedDark、ClearLight、ClearDark
widthnumber1024输出宽度(16–2048)
heightnumber1024输出高度(16–2048)
scalenumber1缩放系数(1–3)
light_anglenumber—光照角度(0–360)
tint_colornumber—色调(0–1)
tint_strengthnumber—色调强度(0–1)
画布选项——与 export_preview 相同
return_imagebooleantrue以 base64 内联形式返回渲染后的图片
export_marketing

 

export_marketing

用于 App Store Connect 的平面营销 PNG。无玻璃效果,不含 Alpha 通道。

参数类型默认值说明
bundle_pathstring—Bundle 路径
output_pathstring—输出 PNG 路径
sizenumber1024输出尺寸(16–2048)
return_imagebooleantrue以 base64 内联形式返回渲染后的图片

MCP 提示词
提示词参数说明
create-app-iconimage_path、output_dir、brand_color、dark_color?引导式工作流:从 Logo 创建图标、预览、迭代并导出
add-dark-modebundle_path、dark_color为现有图标添加深色模式,并提供前后对比预览
export-for-app-storebundle_path、output_dir导出营销 PNG 和预览图,用于提交至 App Store

示例工作流

创建品牌图标
# 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
为 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
带玻璃效果的多层图标
# 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

限制

  • Liquid Glass 渲染需要 macOS,并安装 Apple 的 Icon Composer.app。平面渲染可在任何环境下使用。
  • ClearLight/ClearDark 渲染效果会以灰色为背景。Apple 的玻璃透明效果需要 Metal GPU,无法通过 CLI 使用。

架构

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)

贡献

# 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

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。