What is the Icon Composer MCP server?
The Icon Composer MCP server gives an AI coding agent 12 tools for creating and editing Apple .icon bundles. It sets Liquid Glass effects, background fills and dark or tinted variants, then renders previews and exports a flat 1024 by 1024 App Store icon. Start it with npx -y icon-composer-mcp.
Icon Composer MCP is a CLI and MCP server for creating images, icons and logos with Liquid Glass effects for iOS 26 and later. It builds Apple .icon bundles from a PNG or SVG glyph. The project is not affiliated with Apple.
The server uses stdio and exposes 12 tools plus 3 workflow prompts. Apple's ictool renders the Liquid Glass look, including specular highlights, shadows, depth and translucency.
What it changes in your workflow
- Your agent creates an .icon bundle from a logo and a brand color instead of you assembling layers by hand.
- It sets background fills, layer scale and glass effects, and adds dark and tinted appearance overrides.
- It renders previews as it goes, so the agent can iterate on how the icon looks before export.
- It exports a flat 1024 by 1024 PNG with no alpha channel for App Store Connect.
- The same operations are available as CLI commands when you want to script them without an agent.
Requirements and platforms
| Icon Composer MCP | |
|---|---|
| Transport | stdio |
| Runtime | Node.js 18 or newer |
| Liquid Glass rendering | macOS with Apple's Icon Composer app, installed with brew install --cask icon-composer |
| Works on any platform | Flat previews, bundle creation and editing, and marketing export |
| Setup check | Run icon-composer doctor |
Who it is for
Best for
- iOS and macOS developers who want an agent to produce a Liquid Glass app icon from an existing logo.
- Teams adding dark mode and tinted icon variants without reworking the artwork.
- Developers who want an App Store marketing icon exported in one step.
Not for
- If your job is querying a liquid glass component library for React, Liquefy UI MCP is the better fit for that.
- When the job is looking up Apple Human Interface Guidelines values and SwiftUI mappings, the HIG MCP server is the better fit for that.
- If your job is pulling a color palette and contrast scores from an image, Color Palette Extractor MCP is the better fit for that.
- When the job is editing artwork and batch exports inside Photoshop, the Photoshop Control MCP server is the better fit for that.
Connect Icon Composer MCP: Liquid Glass App Icons from an Agent to your AI client
claude mcp add icon-composer -- npx -y icon-composer-mcpClaude Code
Run the claude mcp add command above.
Other clients
Add the config above to Claude Desktop, Cursor or Windsurf. The docs show the same entry for each, plus a VS Code variant.
VS Code
VS Code uses a servers key instead of mcpServers and needs a type field set to stdio.
Install Icon Composer for glass rendering
On macOS, run brew install --cask icon-composer. Flat previews and marketing export work without it.
Check and try
Run icon-composer doctor to check your setup, then ask the agent to create an icon from your logo with a brand color.
Client configuration
{
"mcpServers": {
"icon-composer": {
"command": "npx",
"args": ["-y", "icon-composer-mcp"]
}
}
}Endpoints and ports
npx -y icon-composer-mcpRuns the server over stdio.npm install -g icon-composer-mcpInstalls the icon-composer command without MCP.icon-composer doctorChecks system setup and dependencies.What you can do with it
- Bundle creationCreates an .icon bundle from a PNG or SVG glyph and a background color, with a glyph scale and a dark mode color.
- Liquid Glass effectsControls specular highlights, blur material, shadows and translucency, per group or all at once.
- Dark and tinted variantsSets per-appearance fills and overrides for dark and tinted modes.
- Layers and groupsAdds layers with opacity, scale, offset and blend mode, and groups them so glass effects apply per group.
- Pixel-perfect renderingRenders the Liquid Glass look through Apple's ictool for iOS, macOS or watchOS, across several renditions.
- App Store exportExports a flat 1024 by 1024 PNG with no alpha channel for App Store Connect.
- Guided promptsThree prompts cover creating an icon from a logo, adding dark mode with a before and after preview, and exporting for App Store submission.
- CLI includedThe same operations run as CLI commands such as create, glass, fill, preview and export-marketing.
Tools it exposes
create_icon
Creates an .icon bundle from a foreground image and a background color, with optional dark color, glyph scale and glass settings.
add_layer_to_icon
Adds a new layer to an existing bundle.
remove_layer
Removes a layer or group, optionally cleaning up assets.
read_icon
Inspects the bundle manifest and assets.
set_glass_effects
Configures specular highlight, blur, shadow and translucency.
set_appearances
Sets dark and tinted mode overrides.
set_fill
Sets the background fill.
set_layer_position
Adjusts layer scale and offset.
toggle_fx
Enables or disables all glass effects at once.
export_preview
Renders a preview PNG.
render_liquid_glass
Renders through Apple's ictool. Requires Icon Composer.
export_marketing
Exports a flat opaque PNG for App Store Connect.
Frequently asked questions
What is the Icon Composer MCP server?
It is a CLI and MCP server that lets an AI coding agent create and edit Apple .icon bundles with Liquid Glass effects for iOS 26 and later. It offers 12 tools and 3 workflow prompts, and it is not affiliated with Apple.
How do I install the Icon Composer MCP server?
Run claude mcp add icon-composer -- npx -y icon-composer-mcp for Claude Code. For other clients, add a server entry with command npx and args -y and icon-composer-mcp. VS Code uses a servers key and needs a type field set to stdio.
Which AI coding agents work with the Icon Composer MCP server?
The docs give setup for Claude Code, Claude Desktop, Cursor, VS Code and Windsurf, and describe a generic stdio entry for other MCP clients. All of them launch the server with npx -y icon-composer-mcp.
Does it only work on a Mac?
Liquid Glass rendering needs macOS with Apple's Icon Composer app. Flat previews, bundle creation and editing, and marketing export work on any platform without it. Run icon-composer doctor to see what your setup supports.
What can I export from it?
You can export a preview PNG, a Liquid Glass render through ictool for iOS, macOS or watchOS, and a flat 1024 by 1024 PNG for App Store Connect with no alpha channel. The .icon bundle itself goes into an Xcode project.
How do I add dark mode to an icon?
Use set_appearances to give the fill, a group or a layer a dark or tinted override, or pass a dark color when creating the icon. The add-dark-mode prompt walks through it with a before and after preview.
What are the known limits?
Liquid Glass rendering requires macOS with Icon Composer installed. The ClearLight and ClearDark renditions render against gray, because Apple's glass transparency needs a Metal GPU that the command line cannot reach.


