Drive PhotoCraft with AI agents over MCP

1. Install photocraft-cli. Install PhotoCraft from the official release; on macOS also download the CLI zip.
2. Choose a working folder. Create a folder the agent may read from and write to.
3. Register the MCP server. Run claude mcp add photocraft -- photocraft-cli mcp with --automation-read-root and --automation-write-root pointing at that folder.
4. Ask the agent. Ask the agent to open, edit and export images inside the folder.

What you can do with it

• Ask an agent to colour-grade, resize or watermark a folder of photos and save the results.
• Inspect a PSD's layer tree, masks and history from a script.
• Render previews so the agent can look at its own work and iterate.
• Batch-process images in CI or on a server, with no window at all.

Step 1: get photocraft-cli

• Windows (MSI): installed as C:\Program Files\PhotoCraft\photocraft-cli.exe, not on PATH.
• Linux (.deb or .rpm): installed as /usr/bin/photocraft-cli.
• macOS: download the separate photocraft-cli-<version>-macos-universal.zip asset. The .app holds only the desktop editor.

Step 2: add it to Claude Code

Pick a working folder the agent may use, then register the server. These commands come from PhotoCraft's own MCP documentation:

# macOS (CLI unzipped onto PATH) or Linux (.deb/.rpm)
claude mcp add photocraft -- photocraft-cli mcp \
  --automation-read-root ~/Pictures/photocraft \
  --automation-write-root ~/Pictures/photocraft

# Windows, default MSI install folder
claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root C:\Users\you\Pictures\photocraft --automation-write-root C:\Users\you\Pictures\photocraft

Claude Desktop and other MCP clients

Clients that take a JSON config use the same command and arguments:

{
  "mcpServers": {
    "photocraft": {
      "command": "photocraft-cli",
      "args": [
        "mcp",
        "--automation-read-root", "/Users/you/Pictures/photocraft",
        "--automation-write-root", "/Users/you/Pictures/photocraft"
      ]
    }
  }
}

The tools the server exposes

Prompts to try

Once the server is connected, talk to the agent normally:

• “Open portrait.psd, list its layers and tell me which ones are hidden.”
• “Add a Curves adjustment layer that lifts the shadows a little, then export a 50% JPEG preview.”
• “For every JPEG in raw/, apply Auto Tone and save a PNG copy in graded/.”
• “Render a preview, look at it, and fix anything that looks over-sharpened.”

Bridge mode: control the running app

Headless mode owns its own engine. To let the agent work in the window you have open, and see the UI, start the desktop app with its control channel and bridge to it:

# 1. Start the desktop app with its control channel.
#    PhotoCraft creates the token file (a fresh 256-bit token) if it doesn't exist.
photocraft --control 7878 --control-token-file ~/.config/photocraft-control.token

# 2. Point the MCP server at the running app with the same token file
photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file ~/.config/photocraft-control.token

Without an agent: the CLI

The same commands work straight from a terminal or a script:

# Headless: open, edit, save
photocraft-cli run wave.psd \
  --cmd filter.sharpen.smartSharpen     --params '{"amount":80}' \
  --cmd layer.newAdjustmentLayer.curves --params '{"points":[[0,0],[64,48],[192,212],[255,255]]}' \
  --out wave-final.png

# Apply one action list to a folder of images
photocraft-cli batch --actions grade.json --in ./raw --out ./graded

# Every subcommand explains itself
photocraft-cli batch --help

Security notes

• Stdio MCP opens no network listener; the client only gets the roots you grant at launch.
• The desktop control channel binds to loopback and needs the bearer token. Keep the token file private and never commit or log it.
• The server doesn't yet distinguish document-only tools from high-impact ones. Don't expose it through untrusted brokers, proxies or remote services.

book/src/automation/mcp.md · docs/control-protocol.md