PhotoCraft MCP Server — Connect PhotoCraft to Claude Code, Cursor and Any AI Agent

What the PhotoCraft MCP server is

PhotoCraft's architecture is command-first: every menu item, tool and dialog runs a command from one registry of 500+ commands. The UI, the headless CLI, the JSON control channel and the MCP server all call that same registry, so anything a person can click in PhotoCraft, an agent can do too — with the same parameters and the same guards.

The MCP server is not a separate product or plugin. It is a subcommand of the CLI that ships with the app (on macOS the CLI comes as photocraft-cli-<version>-macos-universal.zip, signed and notarized like the desktop app). PhotoCraft follows the same MCP conventions as its sibling FilmCraft, so a setup you build for one craft app transfers to the others.

Start it: headless or bridged to the running app

• Headless (no window): photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project — the agent reads and writes only inside the roots you name. Paths can be relative to a root or absolute beneath it; without a root, the server has no filesystem authority at all.
• Bridged to a running app: add --bridge and --control-token-file (documented in the repo's development.md) to drive the desktop app you have open. The ui_inspect and ui_screenshot tools require a running desktop app.
• Plain form from the README: photocraft-cli mcp — headless, or bridged to the running app.
• On Windows and Linux the same CLI ships in each GitHub release next to the desktop builds; use the full path to the binary if it is not on your PATH.

The tools your agent gets

The official docs/mcp.md lists these tools; document, session and job tools (doc_new, doc_save, timeline.create, jobs_list, jobs_cancel) are part of the same surface and appear throughout the same document.

• Two resources, photocraft://document and photocraft://commands, return the same live JSON as doc_inspect and command_list — handy for clients that prefer reading resources over calling tools.
• Unknown tool arguments are rejected before execution (JSON-RPC -32602, naming the offending key), and tool failures surface as isError:true — a worker panic becomes a tool error, not a crash.

Connect Claude Code, Cursor or any MCP client

The server is launched by a command, so any MCP client that starts a local server can run it — point the client at photocraft-cli mcp plus the roots you want to allow. Menus for adding MCP servers move between client versions, so treat these as patterns and your client's documentation as the authority.

• Claude Code (terminal): claude mcp add photocraft -- photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project
• Cursor / Claude Desktop style (JSON): {"mcpServers": {"photocraft": {"command": "photocraft-cli", "args": ["mcp", "--automation-read-root", "/work/project", "--automation-write-root", "/work/project"]}}}
• After connecting, just ask in plain language — 'open wave.psd, sharpen at 80, add a curves adjustment layer, export a PNG'. The agent discovers exact command ids with command_list and runs them with command_run.

The safety model: what an agent can and cannot touch

• Filesystem authority is opt-in: reads and writes are confined to the roots you pass; path traversal, escaping absolute paths and escaping symlinks are rejected.
• Saves are guarded: existing target filenames are refused (including via symlink), so a cancelled or failed job cannot replace an earlier export; only files the job itself created are cleaned up.
• Batches are not transactions: stop_on_error halts at the first failure, but earlier successful steps stay applied. Inspect with doc_inspect and undo with edit.undo, once per history entry — and undo does not roll back files already written to disk.
• Experiment on copies: the docs recommend command_run with image.duplicate or history.newDocument before risky edits — both create a new active document and leave the source unchanged.
• Tools advertise honestly: generic command/control tools conservatively advertise writes, and annotation hints do not grant permission.
• The desktop app's own control channel (photocraft --control) is authenticated and loopback-only — it is what bridge mode rides on, via --control-token-file.

Progress and cancellation on long jobs

Long renders report progress over MCP: a direct headless command_run of file.export.renderVideo reports frame counts when the request carries a progressToken, with notifications throttled to at most ten per second and cancellation stopping at a frame boundary — only files the job created are removed. Two limits to know: render video stays synchronous even with wait:false, and batch exports do not emit MCP progress or support per-step cancellation. For long video exports, use the single command with a progress token rather than a batch step.

More about ArtCraft

More ArtCraft apps

More tutorials

More honest comparisons