PhotoFresco
PhotoFresco is a browser-based, Photoshop-class image editor. Its MCP server (photofresco mcp)
opens PhotoFresco in its own browser window on the user's computer. You edit through one tool per
editor operation; the user sees every change, and every document edit lands in the editor's History.
Use it for real image editing: layers, non-destructive adjustment layers, masks, selections,
crop/resize, filters, painting/retouching tools, text and shapes, PSD round trips. Every edit runs
on the user's computer, and the user must be present: they approve the connection and choose what
you may do.
1. Install the MCP server (once, by the user)
If no photofresco_* tools are available, ask the user to add the server. --read folders are
where you may open files; --write folders are where you may save exports. Without them you can
still create documents, edit and preview, but cannot touch their files.
Claude Code:
claude mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco
Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json or .cursor/mcp.json)
and other clients that take command/args:
{
"mcpServers": {
"photofresco": {
"command": "npx",
"args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
}
}
}
Starting the server and listing tools opens nothing; the browser starts only when you call
photofresco_connect.
2. Connect and ask for permissions
- Call
photofresco_connect with the permissions you need, a short reason and a short wait
("wait_seconds": 10). It opens PhotoFresco and returns either state pairing with a
connection code, or state connected if the user already allowed (then there is no code to
relay; go to step 3).
- Tell the user the code and ask them to check that the PhotoFresco window shows the same code
and click Allow. Until the state is
connected, call photofresco_connect again with a
longer wait (wait_seconds up to 170; the request expires after 3 minutes). Never claim you
approved anything: no tool can answer the user's dialogs.
- The session starts with no permissions. After Allow the user picks them in the
Permissions dialog (pre-filled from your
access request; they may grant less). If
session.grants is still empty, they have not decided yet: call photofresco_status again
until it lists grants (it also shows the pending request and any credit budget). The tool
list changes (tools/list_changed) as permissions arrive.
- Ask for more later with
photofresco_request_access. Ask only for what the task needs:
| Permission |
Lets you |
Ask when |
read (Read) |
Document state, previews, histograms |
Always |
edit (Edit) |
Edit, open files, create and close tabs |
Any change |
export (Export) |
Exports and files leaving the editor |
Saving results (with Read) |
external-write (Send) |
Send document data to PhotoFresco services (cloud documents, AI) |
Only if the user asked for cloud or AI features |
spend (Spend) |
Paid AI up to budget_credits |
Only if the user asked for paid AI, with a budget they agreed to |
A listed tool is documentation, not permission: the editor checks every call, and a call without
the permission fails with capability_denied before anything runs.
3. The editing loop
Orient → change one thing → look → keep or undo.
- Orient. Call
doc_get_state (size, layer tree with IDs, active layer, selection bounds,
document_id, revision) and render_preview to see the image.
- Change one thing. Prefer non-destructive edits:
adjust_add adds an adjustment layer above
the active layer and makes it the active layer (it does not mask itself to the selection);
mask_add with mode: "selection" masks the active layer to the current selection (feather
on a selection softens its edge across the boundary, so the selection bounds grow past the
rectangle); adjust_set_params changes the active adjustment's settings later;
layer_set_props changes opacity, blend mode and visibility. Coordinates are document pixels
from the top-left. Pick the adjustment type from adjust_add's adjustment_type enum (for
example exposure or levels for brightness, color-balance or photo-filter for warmth);
parameter names, ranges and their meaning are in the input schema, and arguments outside it are
refused before anything runs. Curves points: include {"x": 0, "y": 0} and
{"x": 255, "y": 255}, because the first and last points are extended flat to the ends, so a
single point gives a constant output.
- Look.
render_preview (whole image), render_region (a rectangle at detail scale, or one
layer with layer_id) and render_mask (a layer mask or the selection, with coverage numbers)
return PNG images; doc_sample_color gives exact pixel values for before/after numbers. Check
what changed, not just that the call succeeded.
- Keep or undo.
history_undo reverts the last History entry (selection changes count) and
names it in its result (undone); history_redo restores it. Undo also reverts the user's own
last edit if they made one, so check doc_get_state first if they have been editing. For a
clean before/after, add the adjustment with neutral settings, mask it, then apply the settings
with adjust_set_params: one undo then shows the image without the change.
Every result carries document_id and revision; the revision increases with every change by anyone.
Operations act on the session's target document only while it is the active tab.
4. Finding operations
The server lists the essentials group by default: orient, preview, layers, adjustments, masks,
selections, resize/crop, fill, undo and export (about 40 tools). For anything else (brushes and
retouching, text, shapes, layer styles, filters, paths, actions and workflows), call
photofresco_list_tool_groups, then photofresco_select_tool_groups with the groups to add
(document, layers, selection, adjustments, painting, text, automation, workspace,
cloud, other, or all). Read each tool's description: it states the effect, how to undo it and
the permission it needs. Effects that history_undo cannot reverse (closing tabs, saved actions,
cloud writes, paid AI, files written) say so.
Full operation reference: the PhotoFresco agent README
(the generated public reference replaces it once published). The live tool list is always
authoritative.
5. Saving results
photofresco_export_file writes png (flattened, or one layer with layer_id), psd (layered;
PhotoFresco-only features approximated; the result's loss lists what) or pfd (native,
lossless; offer it when the user wants to keep editing in PhotoFresco) into a --write folder.
The file is written only after every byte arrived and its SHA-256 matched; the result's file
gives the written path, bytes and sha256 (its filename is only the editor's default
name for the document). An existing file is replaced only with overwrite: true and the
server's --overwrite option. Paths outside the granted folders are refused (path_not_granted).
export_artifact returns a resource link photofresco://artifact/<id>; read it with MCP
resources/read (at most 6 MiB, kept 10 minutes). Use it when you need the bytes yourself.
- Files are opened with
photofresco_import_file (PNG, JPEG, WebP, GIF, BMP, AVIF, PSD/PSB, .pfd;
at most 32 MiB) from a --read folder only. The user can widen folders only in the server
configuration.
6. What the user controls, and safety rules
- Connection: the user checks the code and clicks Allow. A new connection always needs a new
Allow.
- Permissions: only the user grants or revokes them, at any time. A revoked permission
interrupts work that used it; partial edits stay in History.
- Paid AI (
ai_generate, ai_remove_background, ai_split_layers in the cloud group) needs
Send and Spend plus a credit budget the user sets in the Permissions dialog. Ask only when the
user wants it, say what it will do, and never ask for more budget to retry without telling them.
Credits for a request already sent to the AI provider are not refunded.
- Pause: if the user edits the document, your edits pause (
lease_paused) until they press
Resume. Do not work around it; ask them.
- Stop: the user's Stop ends the session (
session_stopped). Reconnect only if they ask.
- Data: the previews, document state and exports you request are sent to your model provider
under its policy. Tell the user before previewing private images if that matters to them. What
the server runs, sends and fetches is listed in
DISCLOSURE.md in the photofresco package.
- Never try to change PhotoFresco's privacy settings, answer its dialogs, or edit other tabs.
When finished, call photofresco_disconnect (applied edits stay in History; close_window: true
also closes the window).
7. Errors
Failures are tool errors with a code, a message and a hint naming the next step. Follow the
hint. The most common:
| Code |
Do this |
not_connected |
Call photofresco_connect and give the user the code |
capability_denied |
photofresco_request_access with the missing permission and a reason |
lease_paused |
The user edited; ask them to press Resume, then re-read doc_get_state |
document_not_active |
Ask the user to switch to the target tab, or photofresco_attach the active one |
no_target_document |
photofresco_import_file, doc_new or photofresco_attach |
stale_revision |
The document changed; re-read doc_get_state and plan again |
outcome_unknown |
Check doc_get_state before retrying; never repeat blindly |
1---2name: photofresco3description: Edit photos and images in PhotoFresco, a Photoshop-class editor, through its MCP server - layered editing, retouching, adjustment layers (levels, curves, exposure, hue/saturation, brightness/contrast), masks, selections, crop and resize, filters, previews, undo, and PNG/PSD export into folders the user allows. Use when the user wants an image edited, color-corrected, masked, composited or exported with PhotoFresco, or when photofresco_* tools are available. The user watches every edit in a PhotoFresco window on their computer and approves the connection and each permission.4license: MIT5compatibility: Needs the PhotoFresco MCP server (npm package photofresco, Node.js 22 or newer) and Chrome, Edge or Chromium 120+ installed on the user's computer.6metadata:7 source: https://skillmd.com/skills/team/photofresco8 version: "0.1.0"9 homepage: https://photofresco.com/10---1112# PhotoFresco1314PhotoFresco is a browser-based, Photoshop-class image editor. Its MCP server (`photofresco mcp`)15opens PhotoFresco in its own browser window on the user's computer. You edit through one tool per16editor operation; the user sees every change, and every document edit lands in the editor's History.1718Use it for real image editing: layers, non-destructive adjustment layers, masks, selections,19crop/resize, filters, painting/retouching tools, text and shapes, PSD round trips. Every edit runs20on the user's computer, and the user must be present: they approve the connection and choose what21you may do.2223## 1. Install the MCP server (once, by the user)2425If no `photofresco_*` tools are available, ask the user to add the server. `--read` folders are26where you may open files; `--write` folders are where you may save exports. Without them you can27still create documents, edit and preview, but cannot touch their files.2829Claude Code:3031```sh32claude mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco33```3435Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)36and other clients that take `command`/`args`:3738```json39{40 "mcpServers": {41 "photofresco": {42 "command": "npx",43 "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]44 }45 }46}47```4849Starting the server and listing tools opens nothing; the browser starts only when you call50`photofresco_connect`.5152## 2. Connect and ask for permissions53541. Call `photofresco_connect` with the permissions you need, a short reason and a short wait55 (`"wait_seconds": 10`). It opens PhotoFresco and returns either state `pairing` with a56 connection `code`, or state `connected` if the user already allowed (then there is no code to57 relay; go to step 3).582. Tell the user the code and ask them to check that the PhotoFresco window shows the same code59 and click **Allow**. Until the state is `connected`, call `photofresco_connect` again with a60 longer wait (`wait_seconds` up to 170; the request expires after 3 minutes). Never claim you61 approved anything: no tool can answer the user's dialogs.623. The session starts with **no permissions**. After Allow the user picks them in the63 **Permissions** dialog (pre-filled from your `access` request; they may grant less). If64 `session.grants` is still empty, they have not decided yet: call `photofresco_status` again65 until it lists `grants` (it also shows the pending `request` and any credit `budget`). The tool66 list changes (`tools/list_changed`) as permissions arrive.674. Ask for more later with `photofresco_request_access`. Ask only for what the task needs:6869| Permission | Lets you | Ask when |70|---|---|---|71| `read` (Read) | Document state, previews, histograms | Always |72| `edit` (Edit) | Edit, open files, create and close tabs | Any change |73| `export` (Export) | Exports and files leaving the editor | Saving results (with Read) |74| `external-write` (Send) | Send document data to PhotoFresco services (cloud documents, AI) | Only if the user asked for cloud or AI features |75| `spend` (Spend) | Paid AI up to `budget_credits` | Only if the user asked for paid AI, with a budget they agreed to |7677A listed tool is documentation, not permission: the editor checks every call, and a call without78the permission fails with `capability_denied` before anything runs.7980## 3. The editing loop8182**Orient → change one thing → look → keep or undo.**83841. **Orient.** Call `doc_get_state` (size, layer tree with IDs, active layer, selection bounds,85 `document_id`, `revision`) and `render_preview` to see the image.862. **Change one thing.** Prefer non-destructive edits: `adjust_add` adds an adjustment layer above87 the active layer and makes it the active layer (it does not mask itself to the selection);88 `mask_add` with `mode: "selection"` masks the active layer to the current selection (`feather`89 on a selection softens its edge across the boundary, so the selection bounds grow past the90 rectangle); `adjust_set_params` changes the active adjustment's settings later;91 `layer_set_props` changes opacity, blend mode and visibility. Coordinates are document pixels92 from the top-left. Pick the adjustment type from `adjust_add`'s `adjustment_type` enum (for93 example `exposure` or `levels` for brightness, `color-balance` or `photo-filter` for warmth);94 parameter names, ranges and their meaning are in the input schema, and arguments outside it are95 refused before anything runs. Curves points: include `{"x": 0, "y": 0}` and96 `{"x": 255, "y": 255}`, because the first and last points are extended flat to the ends, so a97 single point gives a constant output.983. **Look.** `render_preview` (whole image), `render_region` (a rectangle at detail scale, or one99 layer with `layer_id`) and `render_mask` (a layer mask or the selection, with coverage numbers)100 return PNG images; `doc_sample_color` gives exact pixel values for before/after numbers. Check101 what changed, not just that the call succeeded.1024. **Keep or undo.** `history_undo` reverts the last History entry (selection changes count) and103 names it in its result (`undone`); `history_redo` restores it. Undo also reverts the user's own104 last edit if they made one, so check `doc_get_state` first if they have been editing. For a105 clean before/after, add the adjustment with neutral settings, mask it, then apply the settings106 with `adjust_set_params`: one undo then shows the image without the change.107108Every result carries `document_id` and `revision`; the revision increases with every change by anyone.109Operations act on the session's target document only while it is the **active tab**.110111## 4. Finding operations112113The server lists the `essentials` group by default: orient, preview, layers, adjustments, masks,114selections, resize/crop, fill, undo and export (about 40 tools). For anything else (brushes and115retouching, text, shapes, layer styles, filters, paths, actions and workflows), call116`photofresco_list_tool_groups`, then `photofresco_select_tool_groups` with the groups to add117(`document`, `layers`, `selection`, `adjustments`, `painting`, `text`, `automation`, `workspace`,118`cloud`, `other`, or `all`). Read each tool's description: it states the effect, how to undo it and119the permission it needs. Effects that `history_undo` cannot reverse (closing tabs, saved actions,120cloud writes, paid AI, files written) say so.121122Full operation reference: the [PhotoFresco agent README](https://github.com/photofresco/photofresco-agent#readme)123(the generated public reference replaces it once published). The live tool list is always124authoritative.125126## 5. Saving results127128- `photofresco_export_file` writes `png` (flattened, or one layer with `layer_id`), `psd` (layered;129 PhotoFresco-only features approximated; the result's `loss` lists what) or `pfd` (native,130 lossless; offer it when the user wants to keep editing in PhotoFresco) into a `--write` folder.131 The file is written only after every byte arrived and its SHA-256 matched; the result's `file`132 gives the written `path`, `bytes` and `sha256` (its `filename` is only the editor's default133 name for the document). An existing file is replaced only with `overwrite: true` and the134 server's `--overwrite` option. Paths outside the granted folders are refused (`path_not_granted`).135- `export_artifact` returns a resource link `photofresco://artifact/<id>`; read it with MCP136 `resources/read` (at most 6 MiB, kept 10 minutes). Use it when you need the bytes yourself.137- Files are opened with `photofresco_import_file` (PNG, JPEG, WebP, GIF, BMP, AVIF, PSD/PSB, `.pfd`;138 at most 32 MiB) from a `--read` folder only. The user can widen folders only in the server139 configuration.140141## 6. What the user controls, and safety rules142143- **Connection**: the user checks the code and clicks Allow. A new connection always needs a new144 Allow.145- **Permissions**: only the user grants or revokes them, at any time. A revoked permission146 interrupts work that used it; partial edits stay in History.147- **Paid AI** (`ai_generate`, `ai_remove_background`, `ai_split_layers` in the `cloud` group) needs148 Send and Spend plus a credit budget the user sets in the Permissions dialog. Ask only when the149 user wants it, say what it will do, and never ask for more budget to retry without telling them.150 Credits for a request already sent to the AI provider are not refunded.151- **Pause**: if the user edits the document, your edits pause (`lease_paused`) until they press152 **Resume**. Do not work around it; ask them.153- **Stop**: the user's Stop ends the session (`session_stopped`). Reconnect only if they ask.154- **Data**: the previews, document state and exports you request are sent to your model provider155 under its policy. Tell the user before previewing private images if that matters to them. What156 the server runs, sends and fetches is listed in `DISCLOSURE.md` in the photofresco package.157- Never try to change PhotoFresco's privacy settings, answer its dialogs, or edit other tabs.158159When finished, call `photofresco_disconnect` (applied edits stay in History; `close_window: true`160also closes the window).161162## 7. Errors163164Failures are tool errors with a `code`, a `message` and a `hint` naming the next step. Follow the165hint. The most common:166167| Code | Do this |168|---|---|169| `not_connected` | Call `photofresco_connect` and give the user the code |170| `capability_denied` | `photofresco_request_access` with the missing permission and a reason |171| `lease_paused` | The user edited; ask them to press Resume, then re-read `doc_get_state` |172| `document_not_active` | Ask the user to switch to the target tab, or `photofresco_attach` the active one |173| `no_target_document` | `photofresco_import_file`, `doc_new` or `photofresco_attach` |174| `stale_revision` | The document changed; re-read `doc_get_state` and plan again |175| `outcome_unknown` | Check `doc_get_state` before retrying; never repeat blindly |