ethbak/icon-composer-mcp

CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .
---
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
 
     Claude Desktop
 
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
     Cursor
 
Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):
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.
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:
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:
Or run the server directly:
   CLI only (no MCP)
 
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
- 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
| Command | Description |
|---------|-------------|
| create | Create a new .icon bundle from a foreground image |
| add-layer | Add a layer to an existing bundle |
| remove | Remove a layer or group |
| inspect | Read and display bundle contents |
| glass | Configure Liquid Glass effects on a group |
| appearance | Set dark/tinted mode overrides |
| fill | Set background fill (solid, gradient, automatic, none) |
| position | Set layer/group scale and offset |
| fx | Toggle all glass effects on/off |
| preview | Export a preview PNG (Liquid Glass or flat) |
| render | Render pixel-perfect Liquid Glass via ictool |
| export-marketing | Export flat 1024x1024 PNG for App Store Connect (no alpha) |
| doctor | Check system setup and dependencies |
Details
create — Create a new .icon bundle
 
| Option | Default | Description |
|--------|---------|-------------|
| --bg-color | *required* | Background color (e.g. "#0A66C2") |
| --bundle-name | AppIcon | Bundle name (without .icon extension) |
| --dark-bg-color | — | Dark mode background color |
| --glyph-scale | 1.0 | Glyph scale (1.0 = standard ~65% of icon area) |
| --specular / --no-specular | true | Specular highlight |
| --shadow-kind | layer-color | Shadow type: neutral, layer-color, none |
| --shadow-opacity | 0.5 | Shadow opacity (0–1) |
| --blur-material | — | Blur material value (0–1) |
| --translucency-enabled | false | Enable translucency gradient |
| --translucency-value | 0.4 | Translucency amount (0–1) |
**Output:** Creates / .icon/ containing icon.json manifest and Assets/ directory.
add-layer — Add a layer to an existing bundle
 
| Option | Default | Description |
|--------|---------|-------------|
| --name | *required* | Layer name |
| --group-index | 0 | Target group index |
| --create-group | false | Create a new group for this layer |
| --opacity | 1.0 | Layer opacity (0–1) |
| --scale | 1.0 | Layer scale |
| --offset-x | 0 | X offset in points |
| --offset-y | 0 | Y offset in points |
| --blend-mode | normal | Blend mode (e.g. multiply, screen, overlay) |
| --glass / --no-glass | true | Participate in Liquid Glass effects |