PhotoFresco

[PhotoFresco logo]

PhotoFresco for AI agents

Let AI agents edit images in a PhotoFresco window you approve: layers, masks, previews and export.

[skills.sh] [License: MIT]

PhotoFresco is a free, Photoshop-class image editor that runs in your browser: layers, masks, adjustment layers, selections, brushes, PSD import and export, and full undo history. This repository connects AI agents to it. An agent (Claude, Cursor, VS Code, Codex or any MCP client, or a script through the command line) drives a PhotoFresco window on your own computer. You watch every change, you allow the connection, you choose what the agent may do, and you can pause or stop it at any time. The editing itself happens in the editor, so every change lands in its History and can be undone like your own.

[An agent connects, opens a photo, masks a Hue/Saturation adjustment to the sky, checks a preview and exports a PNG]

The recording above is a real session: an MCP client calling this server against the editor, captured headless. Category: Design / image editing.

What is in this repository:

• MCP server (photofresco mcp): one tool per editor operation, previews as images, exports as files or resources. Guide: MCP.md.
• Agent Skill (skills/photofresco): teaches an agent when and how to use PhotoFresco well.
• Command line (photofresco <command>): open, run saved workflows, export, stop. Guide: CLI.md.
• Local connector (the library the other three share): CONNECTOR.md.

The editor itself is not in this repository; the connector opens it at photofresco.com.

Requirements

• Node.js 22 or newer.
• An installed Chromium-based browser: Google Chrome, Microsoft Edge or Chromium 120 or newer. Nothing is downloaded. Point --browser (or PHOTOFRESCO_BROWSER) at another one if needed.
• macOS is verified; Windows and Linux are implemented but not yet verified.

Configure your agent

One click (Cursor, VS Code, LM Studio):

[Add to Cursor] [Install in VS Code] [Install in VS Code Insiders] [Add to LM Studio]

Each button asks the app to add the photofresco server, started with npx from the GitHub source archive of version 0.1.0 (commit 328cfaf; nothing comes from the npm registry). It grants no folders: add --read and --write arguments after mcp in the app's MCP settings to let the agent open and save files.

Otherwise, add the server to your client's MCP configuration below. Choose the folders the agent may open files from (--read) and save exports into (--write). Without them the agent can still edit and preview, but cannot touch your files.

npm release pending. The photofresco npm package is published in mid-October 2026, so the npx -y [email protected] commands below do not work yet. Until then, put --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco (the same version, from GitHub) in place of [email protected], install the plugin, or run from a clone of this repository as below: node /path/to/photofresco-agent/src/bin/photofresco.js in place of the npx -y [email protected] part (no npm install needed).

From a clone (works today; the MCP SDK is bundled, so there is nothing to install):

git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent

Then add this entry to any client that reads mcpServers (Claude Desktop, Cursor, Windsurf, Kiro and most others), with your own home folder in place of /Users/you:

{  "mcpServers": {    "photofresco": {      "command": "node",      "args": ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]    }  }}

Claude Code:

claude mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config):

{  "mcpServers": {    "photofresco": {      "command": "npx",      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]    }  }}

Cursor: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), with the same mcpServers entry as Claude Desktop.

VS Code: .vscode/mcp.json in a workspace, or MCP: Open User Configuration for all of them:

{  "servers": {    "photofresco": {      "type": "stdio",      "command": "npx",      "args": ["-y", "[email protected]", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]    }  }}

Windsurf (Cascade): the same mcpServers entry as Claude Desktop, in mcp_config.json (Cascade → MCPs → Open MCP config file).

Gemini CLI:

gemini mcp add -s user photofresco npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex:

codex mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

OpenCode: opencode.json in a project, or ~/.config/opencode/opencode.json for all of them (from a clone, as above):

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "photofresco": {      "type": "local",      "command": ["node", "/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"],      "enabled": true    }  }}

Kiro: the clone's mcpServers entry above, in ~/.kiro/settings/mcp.json (all workspaces) or .kiro/settings/mcp.json (one workspace).

Cline: give Cline this repository; llms-install.md walks it through installing, connecting and stopping.

The server is tested with the official MCP TypeScript client over stdio; these entries follow each app's documented stdio format. Options:

MCP Bundle (Claude Desktop and other apps that install .mcpb files): node scripts/build-mcpb.mjs builds dist/photofresco-mcp-0.1.0.mcpb and its SHA-256 from this repository (reproducible with the same Node.js version). The bundle starts the same server and, like a plugin, grants no folders. Each GitHub release attaches this file; its SHA-256 is the fileSha256 in server.json, the Official MCP Registry entry.

Docker (for MCP registries that check servers in a container): docker build -t photofresco-mcp . then docker run -i --rm photofresco-mcp runs the server over stdio. The image has no browser, so it only lists tools; photofresco_connect fails there with browser_not_found. Edit images with a local install as above.

How a session goes

1. The agent calls photofresco_connect. PhotoFresco opens in its own window with a connection code; the agent tells you the same code. Check it and click Allow.
2. The session starts with no permissions. The agent asks for what it needs (Read, Edit, Export; Send and Spend only for cloud and paid AI) and you choose in the Permissions dialog. Editing tools appear for the agent as you grant them.
3. The agent edits with one tool per editor operation, looks at previews and undoes what it does not like. Editing yourself pauses the agent until you press Resume. Stop ends the session; so does closing the window.

Nothing opens until the agent calls photofresco_connect: starting the server and listing its tools starts no browser.

Install as a plugin

This repository is also a plugin for Claude Code, Codex, Cursor, Gemini CLI, Hermes Agent, OpenClaw, Antigravity, Devin and Kiro: one install adds the MCP server and the Agent Skill. The client copies the repository and starts the server with node <plugin folder>/src/bin/photofresco.js mcp; nothing is downloaded from npm, because the MCP SDK is bundled readable in vendor/. Node.js 22 or newer must be on your PATH.

A plugin install grants no folders: the agent edits the image open in the PhotoFresco window, and you open and save files there yourself. For agent file access, configure the server with --read and --write as above instead.

Claude Code (in a session; the third line does both steps in one on Claude Code 2.1.275 or later):

/plugin marketplace add photofresco/photofresco-agent/plugin install photofresco@photofresco/plugin install photofresco --marketplace photofresco/photofresco-agent

Codex:

codex plugin marketplace add photofresco/photofresco-agentcodex plugin add photofresco@photofresco

Gemini CLI:

gemini extensions install https://github.com/photofresco/photofresco-agent

Gemini CLI passes extensions only a few environment variables, so PHOTOFRESCO_BROWSER does not reach this one; with a browser outside the standard locations, use the MCP configuration above.

Cursor: install PhotoFresco from Customize once it is listed, or copy this repository into ~/.cursor/plugins/local/photofresco and reload the window.

Hermes Agent (a version with Agent Plugins support, which has hermes plugins validate). Plugins install disabled; enabling loads the server and skill in the next session:

hermes plugins install photofresco/photofresco-agent --no-enablehermes plugins enable photofresco

OpenClaw (it asks you to review the source, then to accept the plugin's MCP server and skill):

openclaw plugins install photofresco --marketplace photofresco/photofresco-agent

Antigravity (CLI):

agy plugin install https://github.com/photofresco/photofresco-agent

Devin (CLI; or Customize → Plugins → Add plugin → From repository in the app):

devin plugins install photofresco/photofresco-agent

Kiro: Powers → Add Custom Power → Import power from GitHub, then https://github.com/photofresco/photofresco-agent.

The manifests are .claude-plugin/ (Claude Code, also read by Devin), plugin.json with mcp.json (the Agent Plugins standard, used by Codex, Hermes Agent and Kiro), .cursor-plugin/plugin.json (Cursor and OpenClaw, which reads .mcp.json through it), gemini-extension.json (Gemini CLI), mcp_config.json (Antigravity) and openclaw.plugin.json (OpenClaw and ClawHub metadata).

Agent skill

The Agent Skill in skills/photofresco teaches skills-capable agents (Claude Code, Codex, Cursor and others) when to use PhotoFresco, how to connect and ask for permissions, the orient → edit → preview → undo loop, workflows, exports, every error code and the command line. It does not configure the MCP server; set that up as above. Install it with the skills CLI into the current project (-g for your user):

npx skills add photofresco/photofresco-agent

Remove it with npx skills remove photofresco. The operation reference is the server's own tool list (photofresco_list_tool_groups, or photofresco ops on the command line).

Command line

The same package installs a photofresco command for scripts and agents that have a shell but no MCP client. It drives the same kind of approved window through a background connector process. Until the npm package is published (mid-October 2026), run it from a clone instead of npm install -g: alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js".

npm install -g [email protected]photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFrescophotofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \  --export ~/Pictures/PhotoFresco/beach-warm.pngphotofresco stop

connect opens PhotoFresco and prints a connection code; check that the window shows the same code, click Allow and choose the permissions. run opens the image in a new tab, runs a saved workflow (the portable file the editor's Actions panel exports) and writes the export only after its SHA-256 matched. stop ends the session, closes the window and stops the connector process.

Every command takes --json (one object on stdout, also on failure) and returns a documented exit code (0 success, 2 usage, 3 not connected, 4 path refused, 5 refused by the editor, 8 canceled, 75 still waiting for you). Full reference: CLI.md.

What this runs, sends and fetches

Observed on macOS with Chrome for Testing 145 against a local editor build, recorded in DISCLOSURE.md with every detail; anything not observed is marked there.

Runs

• A Node.js process: the MCP server your client starts (it ends when the client closes it), or each photofresco command plus one background connector process per data folder (it ends on photofresco stop, when you close its window, or after a minute with no window or command).
• One browser process tree, only when the agent connects: your installed Chrome, Edge or Chromium, started with a dedicated profile and its DevTools pipe (--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions). It shows a normal, visible window (the demo above was recorded headless). Your everyday browser profiles are never opened, read or attached to.
• No other programs, shell commands, installers, services, login items or extensions.

Local files and channels

• Data folder: ~/Library/Application Support/PhotoFresco Connector (macOS), %LOCALAPPDATA%\PhotoFresco Connector (Windows) or ~/.local/share/photofresco-connector (Linux). It holds the browser profile (cookies and sign-in if you sign in there, cache, the editor's local storage and autosave), a lock file and, for the command line, cli/ with a Unix socket (0600 in a 0700 folder), a per-start random key and connector.log (secret-free events: granted folder paths, paths, sizes and SHA-256 of files read or written; no keys, file contents or pixels; at most 4 MiB).
• Your files: read only inside --read folders when the agent opens a file (at most 32 MiB), and written only inside --write folders when it exports, through a temporary file renamed into place after its SHA-256 matched. Existing files are replaced only with --overwrite and the agent asking for it.
• No listening network port. The browser is controlled over its private pipe; the command line uses the local socket. Observed: no TCP socket in the server or connector process.

Network

• The connector, the MCP server and the command line make no network requests themselves. npx/npm install downloads the package from the npm registry first (the one-click buttons, until the npm release, download this repository's source archive from GitHub instead); a plugin install has the agent client copy this repository (from GitHub), and starting the server downloads nothing.
• The browser opens https://photofresco.com/app/?pf_ref=mcp (or cli), a non-secret tag for attribution, and loads the editor like a normal visit. Because the browser is automated, it shows no third-party ads.
• The connector's window starts with session recording off. The editor recognizes the window the connector opened (a private channel no link or website can set up) and starts it with nothing allowed in Data & privacy, so nothing from your files is uploaded: no session recording, no diagnostics, no copy of the files the agent opens and no usage events. Observed: no recording or telemetry request from connecting to the end of the session, including after the agent imported a photo. Allowing the agent turns on only External agents there.
• Recording stays off unless you turn recording on in Data & privacy in that window. From then on it sends PhotoFresco the input events, editor commands, document names, typed text (password and email fields masked) and a copy of each image opened in the window, including files the agent opens through the connector (at most 16 MiB each, 6 per page load), plus diagnostics (errors, feature events, performance, a device profile) and privacy-safe usage events (referral, open, edit, export, marked automated; no file names or pixels). A normal visit to photofresco.com, not opened by the connector, has recording on by default.
• The browser's own background traffic (updates, safe browsing) follows its defaults; not measured. Third-party requests of the production site were not verified.

What the agent receives

• Only what your grants allow: session status, document state, operation results, previews (pixels) and exported files. Everything the agent receives goes to that agent's model provider, under that provider's policy.
• Paid AI features run only with the Spend permission and the credit budget you set; sending data to PhotoFresco services (cloud documents, AI) needs the Send permission.
• The window shows you who is connecting: the name the MCP client sends in its handshake (" via MCP"), or --client on the command line ("Terminal via CLI" by default).

You stay in control: every connection needs your Allow, a session starts with no permissions, and Stop, closing the window, reloading or leaving the editor ends it. Closing the connector closes its window.

Uninstall

Remove the MCP entry from your client configuration (or run photofresco stop and npm uninstall -g photofresco), or remove the plugin (/plugin uninstall photofresco@photofresco in Claude Code, codex plugin remove photofresco@photofresco, gemini extensions uninstall photofresco, hermes plugins remove photofresco, openclaw plugins uninstall photofresco, agy plugin uninstall photofresco, devin plugins remove photofresco, or Customize in Cursor and the Powers panel in Kiro). Remove the skill with npx skills remove photofresco, and delete the data folder above. Nothing else is installed.

Support

• Questions and bugs: GitHub issues or [email protected].
• Documentation: Use PhotoFresco with AI agents.
• Privacy policy: photofresco.com/docs/privacy.
• Terms of service: photofresco.com/docs/terms.
• Website: photofresco.com.

License

This repository (the MCP server, command line, connector and skill) is released under the MIT License. The PhotoFresco editor and the photofresco.com service are not part of it.