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 .

---

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 mcp add icon-composer -- npx -y icon-composer-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.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):

{

"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.

{

"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:

{

"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:

{

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

Or run the server directly:

npx -y icon-composer-mcp

CLI only (no MCP)

npm install -g icon-composer-mcp

icon-composer --help

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

  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

Details

create — Create a new .icon bundle

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

Output: Creates / .icon/ containing icon.json manifest and Assets/ directory.

add-layer — Add a layer to an existing bundle

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

Supported formats: .png, .jpg, .jpeg, .svg, .webp, .heic, .heif

remove — Remove a layer or group

icon-composer remove <bundle_path> --target <layer|group> --group-index <n> [--layer-index <n>]

inspect — Read and display bundle contents

icon-composer inspect <bundle_path>

Output: Prints the full manifest JSON and lists all assets with sizes.

glass — Configure Liquid Glass effects

icon-composer glass <bundle_path> [options]

appearance — Set dark/tinted mode overrides

icon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]

fill — Set background fill

icon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]

position — Set layer/group scale and offset

icon-composer position <bundle_