photofresco-agent

<p align="center"><img src="assets/logo.png" width="120" height="120" alt="PhotoFresco logo"></p>

# PhotoFresco for AI agents

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

[![skills.sh](https://skills.sh/b/photofresco/photofresco-agent)](https://skills.sh/photofresco/photofresco-agent)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[PhotoFresco](https://photofresco.com/?pf_ref=github) 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](assets/demo.gif)

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](MCP.md).
- **Agent Skill** ([skills/photofresco](skills/photofresco/SKILL.md)): teaches an agent when and how
  to use PhotoFresco well.
- **Command line** (`photofresco <command>`): open, run saved workflows, export, stop. Guide:
  [CLI.md](CLI.md).
- **Local connector** (the library the other three share): [CONNECTOR.md](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):

<!-- install-links:start (generated by scripts/install-links.mjs; edit it there) -->
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=photofresco&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcGFja2FnZT1odHRwczovL2dpdGh1Yi5jb20vcGhvdG9mcmVzY28vcGhvdG9mcmVzY28tYWdlbnQvYXJjaGl2ZS8zMjhjZmFmM2NhZjY0ODNjNTY2MDM4MWYxOWYyYWZkYjIwNTlhMjE1LnRhci5neiIsInBob3RvZnJlc2NvIiwibWNwIl19)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_PhotoFresco-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=photofresco&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%3Dhttps%3A%2F%2Fgithub.com%2Fphotofresco%2Fphotofresco-agent%2Farchive%2F328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz%22%2C%22photofresco%22%2C%22mcp%22%5D%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_PhotoFresco-24bfa5?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=photofresco&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22--package%3Dhttps%3A%2F%2Fgithub.com%2Fphotofresco%2Fphotofresco-agent%2Farchive%2F328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz%22%2C%22photofresco%22%2C%22mcp%22%5D%7D&quality=insiders)
[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-dark.svg)](https://lmstudio.ai/install-mcp?name=photofresco&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcGFja2FnZT1odHRwczovL2dpdGh1Yi5jb20vcGhvdG9mcmVzY28vcGhvdG9mcmVzY28tYWdlbnQvYXJjaGl2ZS8zMjhjZmFmM2NhZjY0ODNjNTY2MDM4MWYxOWYyYWZkYjIwNTlhMjE1LnRhci5neiIsInBob3RvZnJlc2NvIiwibWNwIl19)

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.
<!-- install-links:end -->

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](#install-as-a-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):

```sh
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`:

```json
{
  "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**:

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

```json
{
  "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:

```json
{
  "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**:

```sh
gemini mcp add -s user photofresco npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco
```

**Codex**:

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

```json
{
  "$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](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:

| Option | Meaning |
|---|---|
| `--read <folder>` | The agent may open image files from this folder (repeatable) |
| `--write <folder>` | The agent may save exports into this folder and new subfolders (repeatable) |
| `--overwrite` | Exports may replace existing files in `--write` folders (the agent must also ask for it) |
| `--tools <groups>` | Which operations are listed as tools: `essentials` (default, at most 40 tools), `all`, or a comma list of groups ([MCP.md](MCP.md)) |
| `--profile <folder>` | Browser profile folder, or `ephemeral` for a throwaway one |
| `--browser <path>` | Chromium-based browser to use (same as `PHOTOFRESCO_BROWSER`) |

**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](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