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.

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

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

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

Output: Creates <output_dir>/<bundle_name>.icon/ containing icon.json manifest and Assets/ directory.

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

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

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

icon-composer inspect <bundle_path>

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

icon-composer glass <bundle_path> [options]

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

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

icon-composer position <bundle_path> [options]

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

Enables or disables specular, shadow, blur, and translucency on every group at once.

icon-composer preview <bundle_path> <output_path> [options]

Output: PNG file. Uses Liquid Glass rendering by default (falls back to flat if Icon Composer is not installed).

icon-composer render <bundle_path> <output_path> [options]

Requires: Icon Composer.app installed. Returns an error with install instructions if missing.

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

Output: Flat PNG with no alpha channel (avoids ITMS-90717 rejection). Default 1024x1024.

icon-composer doctor

Output: Reports Node version, platform, ictool path and version. Prints install instructions if Icon Composer is missing.

Create a .icon bundle from a foreground image.

add_layer_to_icon

Add a layer to an existing bundle.

remove_layer

Remove a layer or group. layer_index required when target=layer.

read_icon

Inspect a bundle. Returns full manifest JSON and asset list with sizes.

set_glass_effects

Configure Liquid Glass on a group. All effect parameters are optional — only provided values are changed.

set_appearances

Set dark/tinted overrides for background fill, group effects, or individual layer properties.

set_fill

Set background fill.

set_layer_position

Adjust layer or group scale and offset.

toggle_fx

Enable or disable all glass effects on every group.

export_preview

Render a preview PNG. Uses Liquid Glass by default, falls back to flat.

render_liquid_glass

Pixel-perfect Liquid Glass via Apple's ictool. Requires Icon Composer.app.

export_marketing

Flat marketing PNG for App Store Connect. No glass effects, no alpha channel.