Compositor

io.github.JosusanzPublished by GitHub account Josusanzv0.1.4Updated Oct 24, 2026

Read and edit Compositor .comp projects: layers, folders, masks, transforms, previews and exports

VerifiedSTDIODesktop onlyFiles & StorageMedia & DesignAI & ML

Overview

AI-generated overview

Lets an assistant read and edit Compositor .comp image-editing projects: layers, folders, masks, transforms, previews and PNG/JPEG exports.

What you can do
Works directly on the documented .comp package format (a manifest.json plus one PNG per layer), so no changes to Compositor are needed. Tools include inspect_project, list_layers, render_preview, export_flattened, export_layer, create_project, add_image_layer, add_folder, set_layer, move_layer, remove_layer, replace_layer_image, set_layer_mask, resize_canvas and open_in_compositor. It also exposes a compositor://format resource describing the file format. Layer pixels stay untouched as 8-bit sRGB PNGs, with placement, scale, rotation and flips kept in the layer transform.
When to use it
Use it when you want an agent to build or retouch Compositor projects from the command line: create a document, import images as layers, arrange folders, opacity, blend modes and masks, then render a preview or export flattened PNG/JPEG. It also suits inspecting an existing project saved in Compositor before further edits. It is not a live link to the running app, so selection, undo history and the viewport are out of reach.},
Requirements
Node.js 20 or later; run locally via npx compositor-mcp over stdio. No authentication, environment variables or headers are declared. Compositor itself is only needed to view or further edit the result, and the server is desktop-only.
Before you install
Edits write to project files on disk: create_project, add_image_layer, set_layer, move_layer, remove_layer, replace_layer_image, set_layer_mask, resize_canvas and the export tools all modify or produce files, and manifests are replaced atomically. Fields the tool does not understand are preserved on round trip, but clipping masks, adjustment layers and layer effects are not rendered in previews, so Compositor's own export remains the reference. Compositor does not watch files, so reopen a file (

Installation

In SourceWeft

  1. Open Compositor in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolPurpose
inspect_projectCanvas size, resolution and every layer with folder depth, opacity, blend mode, transform, mask and clipping info
list_layersCompact top-to-bottom view like the Layers panel
render_previewFlattened PNG preview returned as an image so the model can see the composition
export_flattenedFull-resolution PNG or JPEG export
export_layerCopy a layer's source pixels or mask to a file
create_projectNew document, optionally with a solid background layer
add_image_layerImport PNG, JPEG, HEIC, TIFF, WebP… as a layer, with fit/fill/stretch placement, opacity, blend mode and folder
add_folderCreate a layer folder
set_layerRename, show/hide, opacity, blend mode, position, size, rotation, flips, sampling, mask on/off
move_layerReorder layers or move them between folders
remove_layerDelete a layer or a whole folder
replace_layer_imageSwap a layer's pixels (round-trip through another tool or a generated image)
set_layer_maskAttach a grayscale mask, invert it, or clear it
resize_canvasChange the document size with an anchor, without resampling
open_in_compositorOpen the project in the Compositor app

The server also exposes a compositor://format resource describing the file format.

Related

marcushorndt/compositor-mcp takes a different route: it drives Compositor's own document model and renderer headlessly (Swift), so previews match the app exactly. This package is a plain Node server that works on the documented file format, needs no build of the app, and runs wherever Node runs. Pick whichever fits your setup; both open the same .comp files.

Install

Requires Node.js 20 or later. Compositor itself is only needed to look at the result.

Claude Code

bash
claude mcp add compositor -- npx -y compositor-mcp

Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "compositor": {      "command": "npx",      "args": ["-y", "compositor-mcp"]    }  }}

From source

bash
git clone https://github.com/Josusanz/compositor-mcpcd compositor-mcpnpm installnpm run buildclaude 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.

How it maps to the Compositor format

  • 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 saved as format version 9 (what Compositor 1.2.6 writes); a project declaring a newer version keeps its own number and its unknown fields on round trip. 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

bash
npm installnpm test        # builds and runs the node:test suitenpm run dev     # runs the server from TypeScript with tsx

License

MIT. Compositor is © Robbie Tilton, also MIT.

Source: README.md at commit e3d7f54

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.4LatestSep 25, 2026
  2. v0.1.2Sep 22, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts