Icon Composer MCP

探索

Icon Composer MCP

#null .TypeScript

評分 : 2.5分

下載量 : 4.2K

更新時間 : 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