Icon Composer MCP

探索

Icon Composer MCP

#null .TypeScript

评分 : 2.5分

下载量 : 3.1K

更新时间 : 2026-06-17

打开站点

安装

复制以下命令到你的Client进行配置

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

注意：您的密钥属于敏感信息，请勿与任何人分享。

🎨 Icon Composer MCP

用于创建具有 Liquid Glass 效果（iOS 26+）的图像、图标和标志的 CLI 与 MCP 服务器。与 Apple  无任何关联。

📸 演示

✨ 主要特性

以编程方式创建 .icon 套件：支持从 PNG 或 SVG 图形生成
完整 Liquid Glass 支持：镜面高光、模糊材质、阴影、半透明
深色模式 + 外观变体：支持针对每种外观单独定制填充
面向 AI Agent 设计：12 个 MCP 工具 + 3 个工作流提示词，内置操作指引

📦 安装指南

Claude Code

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

Claude Desktop

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

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

Cursor

添加到项目根目录的 .cursor/mcp.json（或全局配置 ~/.cursor/mcp.json）：

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

服务器将出现在 Cursor Settings > MCP Servers 中。无需重启。

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"]
    }
  }
}

你将在编辑器中看到内联的 Start/Stop/Restart 按钮。首次启动时会弹出信任确认提示。

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

🔧 工作原理

提供一个图形 —— 任意 PNG 或 SVG 标志/图像
创建 .icon 套件 —— 设置背景填充、图层缩放和玻璃效果
由 Apple 的 ictool 渲染 Liquid Glass —— 镜面高光、阴影、深度和半透明
导出 —— 预览 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` 套件
`add-layer`	向已有套件添加图层
`remove`	移除图层或组
`inspect`	读取并显示套件内容
`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 套件

icon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]

选项	默认值	描述
`--bg-color <hex>`	必填	背景颜色（例如 `"#0A66C2"`）
`--bundle-name <name>`	`AppIcon`	套件名称（不含 `.icon` 扩展名）
`--dark-bg-color <hex>`	—	深色模式背景颜色
`--glyph-scale <n>`	`1.0`	图形缩放比例（1.0 = 标准，约占图标区域的 65%）
`--specular / --no-specular`	`true`	镜面高光
`--shadow-kind <kind>`	`layer-color`	阴影类型：`neutral`、`layer-color`、`none`
`--shadow-opacity <n>`	`0.5`	阴影不透明度（0–1）
`--blur-material <n>`	—	模糊材质值（0–1）
`--translucency-enabled`	`false`	启用半透明渐变
`--translucency-value <n>`	`0.4`	半透明程度（0–1）

输出： 创建 <output_dir>/<bundle_name>.icon/，其中包含 icon.json 清单和 Assets/ 目录。

add-layer — 向已有套件添加图层

icon-composer add-layer <bundle_path> <image_path> --name <name> [options]

选项	默认值	描述
`--name <name>`	必填	图层名称
`--group-index <n>`	`0`	目标组索引
`--create-group`	`false`	为该图层创建新组
`--opacity <n>`	`1.0`	图层不透明度（0–1）
`--scale <n>`	`1.0`	图层缩放
`--offset-x <n>`	`0`	X 轴偏移（单位：点）
`--offset-y <n>`	`0`	Y 轴偏移（单位：点）
`--blend-mode <mode>`	`normal`	混合模式（例如 `multiply`、`screen`、`overlay`）
`--glass / --no-glass`	`true`	是否参与 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 — 读取并显示套件内容

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>`	`layer`	`layer` 或 `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`
`--flat`	`false`	强制平面渲染（跳过 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>`	`iOS`	`iOS`、`macOS` 或 `watchOS`
`--rendition <name>`	`Default`	`Default`、`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_path`	string	是	—	PNG 或 SVG 的绝对路径
`output_dir`	string	是	—	输出目录
`bundle_name`	string	否	`AppIcon`	套件名称
`bg_color`	string	是	—	背景十六进制颜色
`dark_bg_color`	string	否	—	深色模式背景颜色
`glyph_scale`	number	否	`1.0`	图形缩放（0.1–2.0）
`specular`	boolean	否	`true`	镜面高光
`shadow_kind`	enum	否	`layer-color`	`neutral`、`layer-color`、`none`
`shadow_opacity`	number	否	`0.5`	阴影不透明度（0–1）
`blur_material`	number	否	—	模糊量（0–1）
`translucency_enabled`	boolean	否	`false`	启用半透明
`translucency_value`	number	否	`0.4`	半透明程度（0–1）

add_layer_to_icon

`add_layer_to_icon`

向已有套件添加图层。

参数	类型	必填	默认值	描述
`bundle_path`	string	是	—	`.icon` 套件路径
`image_path`	string	是	—	图像文件路径
`layer_name`	string	是	—	图层名称
`group_index`	number	否	`0`	目标组
`create_group`	boolean	否	`false`	创建新组
`opacity`	number	否	`1.0`	图层不透明度（0–1）
`scale`	number	否	`1.0`	图层缩放（0.1–2.0）
`offset_x`	number	否	`0`	X 轴偏移
`offset_y`	number	否	`0`	Y 轴偏移
`blend_mode`	enum	否	`normal`	混合模式
`glass`	boolean	否	`true`	是否参与玻璃效果

remove_layer

`remove_layer`

移除图层或组。当 target=layer 时，layer_index 为必填项。

参数	类型	必填	默认值
`bundle_path`	string	是	—
`target`	enum	是	—
`group_index`	number	是	—
`layer_index`	number	否	—
`cleanup_assets`	boolean	否	`true`

read_icon

`read_icon`

检查套件。返回完整的清单 JSON 及带大小的资源列表。

参数	类型	必填
`bundle_path`	string	是

set_glass_effects

`set_glass_effects`

在组上配置 Liquid Glass。所有效果参数均为可选项 —— 只有传入的值会被修改。

参数	类型	默认值	描述
`bundle_path`	string	—	套件路径
`group_index`	number	`0`	目标组
`specular`	boolean	—	镜面高光开关
`blur_material`	number\|null	—	模糊（0–1，null 表示禁用）
`shadow_kind`	enum	—	`neutral`、`layer-color`、`none`
`shadow_opacity`	number	—	阴影不透明度（0–1）
`translucency_enabled`	boolean	—	半透明开关
`translucency_value`	number	—	半透明程度（0–1）
`opacity`	number	—	组不透明度（0–1）
`blend_mode`	enum	—	混合模式
`lighting`	enum	—	`combined` 或 `individual`

set_appearances

`set_appearances`

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

参数	类型	必填	描述
`bundle_path`	string	是	套件路径
`target`	enum	是	`fill`、`group` 或 `layer`
`appearance`	enum	是	`dark` 或 `tinted`
`group_index`	number	否	组索引（用于 `target=group` 或 `target=layer`）
`layer_index`	number	否	组内图层索引（当 `target=layer` 时必填）
`bg_color`	string	否	该外观下的背景颜色（target=fill）
`specular`	boolean	否	该外观下的镜面高光（target=group）
`shadow_kind`	enum	否	阴影类型（target=group）
`shadow_opacity`	number	否	阴影不透明度（target=group）
`opacity`	number	否	该外观下的不透明度（target=group 或 target=layer）
`blur_material`	number\|null	否	该外观下的模糊材质（target=group）
`translucency_enabled`	boolean	否	该外观下启用半透明（target=group）
`translucency_value`	number	否	该外观下的半透明程度（target=group）
`hidden`	boolean	否	该外观下的隐藏状态（target=group 或 target=layer）
`blend_mode`	enum	否	该外观下的混合模式（target=layer）
`fill_color`	string	否	该外观下的填充颜色十六进制值（target=layer）
`position_scale`	number	否	该外观下的位置缩放（0.05–3.0）
`position_offset_x`	number	否	该外观下的位置 X 轴偏移
`position_offset_y`	number	否	该外观下的位置 Y 轴偏移

set_fill

`set_fill`

设置背景填充。

参数	类型	必填	描述
`bundle_path`	string	是	套件路径
`fill_type`	enum	是	`solid`、`gradient`、`automatic`、`none`
`color`	string	否	十六进制颜色（纯色或渐变底部）
`color2`	string	否	渐变顶部颜色
`gradient_angle`	number	否	角度（单位：度，默认：`0`）

set_layer_position

`set_layer_position`

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

参数	类型	默认值	描述
`bundle_path`	string	—	套件路径
`target`	enum	`layer`	`layer` 或 `group`
`group_index`	number	`0`	组索引
`layer_index`	number	—	图层索引（用于 `target=layer`）
`scale`	number	—	缩放（0.05–3.0）
`offset_x`	number	—	X 轴偏移
`offset_y`	number	—	Y 轴偏移

toggle_fx

`toggle_fx`

启用或禁用所有组上的全部玻璃效果。

参数	类型	必填
`bundle_path`	string	是
`enabled`	boolean	是

export_preview

`export_preview`

渲染预览 PNG。默认使用 Liquid Glass，回退为平面渲染。

参数	类型	默认值	描述
`bundle_path`	string	—	套件路径
`output_path`	string	—	输出 PNG 路径
`size`	number	`1024`	输出尺寸（16–2048）
`appearance`	enum	—	`dark` 或 `tinted`
`flat`	boolean	`false`	强制平面渲染
`canvas_bg`	enum	—	预设背景
`apple_preset`	enum	—	Apple 壁纸预设
`canvas_bg_color`	string	—	自定义背景十六进制颜色
`canvas_bg_image`	string	—	背景图像路径
`zoom`	number	`1.0`	缩放级别（0.1–3.0）
`return_image`	boolean	`true`	以内联 base64 形式返回渲染图像

render_liquid_glass

`render_liquid_glass`

通过 Apple 的 ictool 渲染像素级精确的 Liquid Glass。需安装 Icon Composer.app。

参数	类型	默认值	描述
`bundle_path`	string	—	套件路径
`output_path`	string	—	输出 PNG 路径
`platform`	enum	`iOS`	`iOS`、`macOS`、`watchOS`
`rendition`	enum	`Default`	`Default`、`Dark`、`TintedLight`、`TintedDark`、`ClearLight`、`ClearDark`
`width`	number	`1024`	输出宽度（16–2048）
`height`	number	`1024`	输出高度（16–2048）
`scale`	number	`1`	缩放倍率（1–3）
`light_angle`	number	—	光照角度（0–360）
`tint_color`	number	—	色调色相（0–1）
`tint_strength`	number	—	色调强度（0–1）
画布选项	—	—	与 `export_preview` 相同
`return_image`	boolean	`true`	以内联 base64 形式返回渲染图像

export_marketing

`export_marketing`

用于 App Store Connect 的平面营销 PNG。无玻璃效果，无 alpha 通道。

参数	类型	默认值	描述
`bundle_path`	string	—	套件路径
`output_path`	string	—	输出 PNG 路径
`size`	number	`1024`	输出尺寸（16–2048）
`return_image`	boolean	`true`	以内联 base64 形式返回渲染图像

📝 MCP 提示词

提示词	参数	描述
`create-app-icon`	`image_path`、`output_dir`、`brand_color`、`dark_color?`	引导式工作流：从 logo 创建图标、预览、迭代、导出
`add-dark-mode`	`bundle_path`、`dark_color`	为已有图标添加深色模式，并提供前后对比预览
`export-for-app-store`	`bundle_path`、`output_dir`	导出用于 App Store 提交的营销 PNG + 预览

🎯 示例工作流

创建品牌图标

# 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