# Compositor

An MCP server for reading and editing Compositor projects through an agent: layers, folders, masks, transforms, previews, exports. Useful when a layout needs retouching without opening the Mac editor manually.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 8 repo stars
- Author: Josusanz
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Josusanz/compositor-mcp
- Updated: 2026-09-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/compositor

## What it does

It works directly with the `.comp` package: a `manifest.json` file plus one PNG per layer. The agent does not need a running Compositor app to inspect or change a project. It reads the files, edits the layer data, and writes them back for later use in Compositor.

The server includes tools such as `create_project`, `add_image_layer`, `set_layer`, `move_layer`, `remove_layer`, `replace_layer_image`, `set_layer_mask`, `resize_canvas`, `render_preview`, `export_flattened`, `export_layer`, and `open_in_compositor`. Preview output comes back as a PNG image, so the model can see the flattened composition before exporting. Fields the tool does not understand, like text, shapes, effects, or adjustment layers, stay intact on a round trip.

Installation requires Node.js 20 or later. One real limitation: the preview renderer skips clipping masks, adjustment layers, and layer effects. Compositor also does not watch project files, so after the agent edits an open document you have to close and reopen it.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add compositor -- npx -y compositor-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add compositor -- npx -y compositor-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "compositor": {
            "command": "npx",
            "args": [
                "-y",
                "compositor-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "compositor": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "compositor-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add compositor npx -y compositor-mcp
```

## When to use it
- create a new .comp document with a solid background
- add photos and logos as layers with blend modes
- export a layer's pixels or mask to a file
- reorder layers and folders before opening the result
- attach an inverted grayscale mask to a layer

## Example prompts
- Change `logo` to 60% opacity and move it to the top left.
- Export `poster.comp` as a flattened JPEG and return the file.

## Similar
- [scenario-video-assembly](https://affpapa.org/en/nevibecode/skills/scenario-video-assembly.md) — skill · 919 installs
- [image-edit](https://affpapa.org/en/nevibecode/skills/image-edit.md) — skill · 448100 installs
- [image-outpainting](https://affpapa.org/en/nevibecode/skills/image-outpainting.md) — skill · 387500 installs
- [scenario-image](https://affpapa.org/en/nevibecode/skills/scenario-image.md) — skill · 1100 installs
- [cli-anything-gimp](https://affpapa.org/en/nevibecode/skills/cli-anything-gimp.md) — skill · 710 installs
- [openrouter-images](https://affpapa.org/en/nevibecode/skills/openrouter-images.md) — skill · 580 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
