PhotoFresco

PhotoFresco for AI agents

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

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.

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 ): 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):

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 photofresco@0.1.0 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 photofresco@0.1.0, 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 photofresco@0.1.0 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 photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

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

{

"mcpServers": { "photofresco": { "command": "npx", "args": ["-y", "photofresco@0.1.0", "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", "photofresco@0.1.0", "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 photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex:

codex mcp add photofresco -- npx -y photofresco@0.1.0 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 /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-agent

codex 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 sk