Photocraft MCP Server – Install, Setup & Tools

Set up the Photocraft MCP server in Claude Code, Claude Desktop, Cursor or VS Code: one CLI command exposes the editor engine with scoped file permissions.

What is the Photocraft MCP server?

The Photocraft MCP server is a Model Context Protocol endpoint built into the PhotoCraft automation stack. It speaks MCP over standard input and output, so an AI client such as Claude Code, Claude Desktop, Cursor or VS Code can discover editing commands, run them one at a time or in batches, inspect the open document and render previews — without anyone clicking through the interface.

The server ships inside photocraft-cli, the command-line companion of the open-source PhotoCraft desktop editor. This website hosts the PhotoCraft web editor that runs in your browser; the MCP server belongs to the desktop release, and the browser build does not expose it. Everything below follows the upstream v0.12.0 release that this site tracks, checked against the upstream documentation in October 2026.

What you need

A PhotoCraft release install that includes photocraft-cli (see the table below).
An MCP client that can register a stdio server: Claude Code, Claude Desktop, Cursor, VS Code and similar tools qualify.
A working folder for your images. The server only reads and writes inside the roots you grant it at launch.

Where the CLI lives

System	CLI location
Windows (MSI)	`C:\Program Files\PhotoCraft\photocraft-cli.exe` by default; not added to `PATH`
Linux (deb, rpm)	`/usr/bin/photocraft-cli`
macOS	a separate `photocraft-cli` zip on the releases page; the `.app` bundle holds only the desktop app

Add the server to Claude Code

Claude Code registers a stdio server with one command. Pass the folder the agent may read and write. On Windows, with the default install folder:

claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root "C:\work\project" --automation-write-root "C:\work\project"

On Linux — or macOS with the CLI unzipped onto PATH — the same registration is shorter:

claude mcp add photocraft -- photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project

Restart the client and ask the agent to list the Photocraft tools. If command_list returns engine commands, the registration worked.

Claude Desktop, Cursor and VS Code

Clients that read a JSON configuration use the same command and arguments. For Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "photocraft": {
      "command": "/usr/bin/photocraft-cli",
      "args": [
        "mcp",
        "--automation-read-root",
        "/work/project",
        "--automation-write-root",
        "/work/project"
      ]
    }
  }
}

On Windows, point command at the full photocraft-cli.exe path and keep the quotes around it. VS Code accepts the same mcpServers block in its mcp.json. Save the file, restart the client and open its MCP panel: the photocraft server should appear with its tools listed.

Headless and bridge modes

The server runs in two backends. Headless mode — the setup above — starts a private engine inside the CLI process and performs its own file I/O. No desktop window is needed, which suits scripted batch work.

Bridge mode forwards every tool call to a desktop application that you started with photocraft --control:

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

Bridge mode adds the UI inspection tools listed below and uses the roots configured on the desktop process. Choose it when you want to watch the same document on screen while the agent works.

Core tools

Tool	What it does	Key arguments
`command_list`	Discover engine command ids, parameter docs and enabled state	`filter`, `enabled_only`
`command_run`	Run one engine command	`id`, `params`, `wait`
`command_batch`	Run ordered steps as one history entry; not an atomic transaction	`steps`, `stop_on_error`
`doc_inspect`	Layer tree, history and selection; an empty session answers `document: null`	—
`render_preview`	Bounded PNG preview of the current document	`index`, `max_side` (default 1024, max 2048)
`ui_inspect`, `ui_screenshot`	Live app state and window capture; bridge mode only	—

Older document, session and job tools remain listed, including the documented doc_render_preview spelling. There are no hidden legacy aliases, and every tool carries a title and annotation hints.

Two MCP resources expose live state as JSON: photocraft://document mirrors doc_inspect and photocraft://commands mirrors command_list. Resource reads are uncached, so an agent can re-check state between steps instead of trusting a stale copy.

Example prompts

List the Photocraft commands for resizing and export, then batch-convert every PNG in the granted folder to 1600 pixels on the long edge.
Inspect the open document, describe the layer stack, and render a preview so I can check the current state.
Create a document and timeline, render a PNG sequence with progress notifications, and cancel the job if it takes more than a minute.

Smart objects are scriptable as well. layer.smartObjects.editContents and layer.smartObjects.convertToLayers run through command_run; save nested contents from the inside outward, then doc_save the parent to a scoped path.

Render Video reports frame progress when the request carries a progress token and stops at a frame boundary when cancelled. Existing filenames are refused, so a cancelled or failed job cannot replace an earlier export.

Security model

Stdio transport opens no network listener; the client talks to the CLI over its own pipes. File authority is granted per launch: the read root and write root are the only folders the server may touch, and omitting a root removes that authority entirely. Paths must resolve inside the granted roots. Bridge mode authenticates its loopback connection with a bearer token before any control call.

Two limits matter. The current server does not issue scoped sessions, and it does not separate trusted from high-impact tools: authentication proves possession of the token, not document-only access. Do not expose either transport through an untrusted broker, shell wrapper, proxy or remote service without adding an external policy boundary. Filesystem capabilities are implemented; general tool capabilities remain a proposed upstream design.

Troubleshooting

photocraft-cli not found on Windows — the MSI install does not edit PATH. Use the full quoted path in the registration command.
No CLI on macOS after installing — the .app contains only the desktop editor. Take the separate photocraft-cli macOS zip from the release assets.
-32602 on a tool call — an unknown argument name. The error names the offending key before anything executes. Check spelling against command_list output.
Tool result with isError: true — the command itself failed. Read the message; the session keeps serving.
document: null from doc_inspect — no document is open. Create or open one first.
Preview looks stale — previews render the current document. Confirm the agent edited the document it inspected, and re-read the live resource; reads are uncached.

Frequently asked questions

Can I connect MCP to the web editor on this site? No. The browser build runs locally in your tab and has no MCP endpoint. The server ships with the desktop release. You can try the editor in your browser and run the CLI beside it on the files you export.

Do I need the desktop app running? Only for bridge mode and the UI tools. Headless mode runs entirely inside the CLI.

Which version does this guide describe? Upstream v0.12.0, the release this site pins and hosts. Newer releases can add or change tools; the linked upstream MCP documentation is authoritative.

What does it cost? PhotoCraft is open source under MIT and Apache-2.0, and the MCP server is part of the same package. See the source and licensing page.