compositor-mcp
An MCP server that lets Claude and other AI agents read and edit
Compositor projects, the open-source Photoshop
alternative for Mac.
It works on the documented .comp package format (a manifest.json plus one PNG per layer), so it
needs no changes to Compositor itself. Edit a project with an agent, then open it in Compositor.
Or the other way round: save in Compositor and let the agent inspect, retouch or render it.
What the agent can do
| Tool | Purpose |
|---|
inspect_project | Canvas size, resolution and every layer with folder depth, opacity, blend mode, transform, mask and clipping info |
list_layers | Compact top-to-bottom view like the Layers panel |
render_preview | Flattened PNG preview returned as an image so the model can see the composition |
export_flattened | Full-resolution PNG or JPEG export |
export_layer | Copy a layer's source pixels or mask to a file |
create_project | New document, optionally with a solid background layer |
add_image_layer | Import PNG, JPEG, HEIC, TIFF, WebP… as a layer, with fit/fill/stretch placement, opacity, blend mode and folder |
add_folder | Create a layer folder |
set_layer | Rename, show/hide, opacity, blend mode, position, size, rotation, flips, sampling, mask on/off |
move_layer | Reorder layers or move them between folders |
remove_layer | Delete a layer or a whole folder |
replace_layer_image | Swap a layer's pixels (round-trip through another tool or a generated image) |
set_layer_mask | Attach a grayscale mask, invert it, or clear it |
resize_canvas | Change the document size with an anchor, without resampling |
open_in_compositor | Open the project in the Compositor app |
The server also exposes a compositor://format resource describing the file format.
Install
Requires Node.js 20 or later. Compositor itself is only needed to look at the result.
Claude Code
claude mcp add compositor -- npx -y compositor-mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"compositor": {
"command": "npx",
"args": ["-y", "compositor-mcp"]
}
}
}
From source
git clone https://github.com/Josusanz/compositor-mcp
cd compositor-mcp
npm install
npm run build
claude mcp add compositor -- node /path/to/compositor-mcp/dist/src/index.js
Example session
Create a 1920×1080 project at ~/Desktop/poster.comp with a white background, add photo.jpg
scaled to fill, put logo.png in the bottom right corner at 80 % opacity with Multiply, then show
me a preview and open it in Compositor.
The agent calls create_project, add_image_layer twice, set_layer, render_preview and
open_in_compositor. Compositor opens the document with the layers ready to keep editing.
- Layer pixels are stored untouched as 8-bit sRGB PNGs; placement, scale, rotation and flips live
in the layer transform, so edits stay non-destructive.
- Masks are written as 8-bit grayscale PNGs without alpha, as Compositor requires.
- Manifests are validated against the same rules as
ProjectStore.swift before writing, written
with sorted keys and replaced atomically.
- Fields this tool does not understand (adjustments, effects, text, shapes, guides, anything newer)
are preserved on round trip.
- Projects are always saved as format version 8 (the current one). Older Compositor builds reject
newer versions; update the app if a file will not open.
Limitations
- The preview renderer covers order, folders, visibility, opacity, transforms, raster masks and
the blend modes sharp supports. Clipping masks, adjustment layers and layer effects are not
rendered yet; the tool reports what it skipped. Compositor's own export is the reference.
- Compositor does not watch files for changes. After the agent edits a project that is already
open, close and reopen the document (or call
open_in_compositor).
- There is no live connection to the running app: selection, undo history and the viewport are
session-only in Compositor and out of reach here.
Development
npm install
npm test
npm run dev
License
MIT. Compositor is © Robbie Tilton, also MIT.