PhotoCraft MCP Server — Let AI Agents Edit Images

MCP needs the desktop app or CLI. The browser editor on this site can’t be driven by an agent; for prompt-based edits in the browser, use the AI panel.

Two ways to run it

Mode	What the agent drives	Use it for
Headless	An in-process engine, no window	Batch jobs, pipelines, servers
Bridge	The running desktop app, over a local control channel	Working alongside the agent and watching each step

Set up with Claude Code (headless)

Get photocraft-cli (the macOS release ships it as photocraft-cli-0.7.0-macos-universal.zip; on other systems build it with cargo build --release -p photocraft-cli), make a working folder, then register the server:

mkdir -p "$PWD/photocraft-work"
claude mcp add photocraft -- /path/to/photocraft-cli mcp \
  --automation-read-root "$PWD/photocraft-work" \
  --automation-write-root "$PWD/photocraft-work"

Or add it to .mcp.json in your project:

{
  "mcpServers": {
    "photocraft": {
      "command": "/path/to/photocraft-cli",
      "args": ["mcp",
        "--automation-read-root", "/absolute/path/to/workspace",
        "--automation-write-root", "/absolute/path/to/workspace"]
    }
  }
}

The two root flags are the agent’s only file access. Leave one out and that direction is denied.

Drive the live desktop app (bridge)

Start the app with its control channel and the folders it may use, then point the CLI at it:

photocraft --control 7878 --control-token-file ~/.photocraft-token \
  --automation-read-root ~/photocraft-work --automation-write-root ~/photocraft-work

photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file ~/.photocraft-token

Bridge mode adds tools that see and use the interface: ui_inspect, ui_screenshot, ui_pointer, ui_menu_invoke and ui_set.

What the agent gets

Documents: doc_open, doc_new, doc_place, doc_save, doc_export, doc_inspect (layer tree, history, selection), doc_render_preview (returns a PNG the model can look at).
Commands: command_list to discover the 500+ engine commands and their parameters, command_run for one, command_batch for several in order.
Jobs: jobs_list and jobs_cancel for long-running work.

A good habit from the project’s own docs: have the agent run image.duplicate first and experiment on the copy, and use doc_inspect after a failed batch, since batches are not rolled back.

Prompts to try

“Open poster.psd, list the text layers, change the headline to ‘Summer Sale’ and export a 1080 px PNG.”
“For every JPEG in raw/, add a Curves layer that lifts the shadows slightly, then export to graded/.”
“Render a preview of the current document and tell me which layers are hidden.”

Without MCP: the CLI on its own

# Open, edit and save in one command
photocraft-cli run wave.psd \
  --cmd filter.sharpen.smartSharpen --params '{"amount":80}' \
  --out wave-final.png

# One action list over a folder
photocraft-cli batch --actions grade.json --in ./raw --out ./graded

FAQ

Can an AI agent control the browser version on this site?

No. The MCP server is part of photocraft-cli and talks to a headless engine or to the desktop app. The web build has no control channel. Use the AI panel here for prompt-based image edits, and the desktop app or CLI for agent automation.

Which agents work with it?

Any MCP client that can launch a local stdio server: Claude Code, Claude Desktop, Cursor, VS Code agents and others. The project documents a Claude Code setup; other clients take the same command and arguments.

Can the agent read or delete files anywhere on my disk?

Only inside the folders you pass with --automation-read-root and --automation-write-root. Without those flags the server has no file access at all. Point them at a dedicated working folder.

Source: PhotoCraft’s MCP conventions and development notes. Flags can change between releases; check photocraft-cli mcp --help.