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

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:
photofresco mcp): one tool per editor operation, previews as images, exports
as files or resources. Guide: MCP.md.photofresco <command>): open, run saved workflows, export, stop. Guide:
CLI.md.The editor itself is not in this repository; the connector opens it at photofresco.com.
--browser (or PHOTOFRESCO_BROWSER) at another one if needed.One click (Cursor, VS Code, LM Studio):
Each button asks the app to add the photofresco server, started with
npx -y [email protected] mcp. 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.
The commands below run the published npm package. To run the same server from a clone of this repository instead, use
node /path/to/photofresco-agent/src/bin/photofresco.jsin place of thenpx -y [email protected]part (nonpm installneeded), or install the plugin.
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-agentThen 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/PhotoFrescoClaude 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/PhotoFrescoCodex:
codex mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFrescoOpenCode: 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:
| 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) |
--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.2.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.
photofresco_connect. PhotoFresco opens in its own window with a connection
code; the agent tells you the same code. Check it and click Allow.Nothing opens until the agent calls photofresco_connect: starting the server and listing its
tools starts no browser.
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-agentCodex:
codex plugin marketplace add photofresco/photofresco-agent
codex plugin add photofresco@photofrescoGemini CLI:
gemini extensions install https://github.com/photofresco/photofresco-agentGemini 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-enable
hermes plugins enable photofrescoOpenClaw (it asks you to review the source, then to accept the plugin's MCP server and skill):
openclaw plugins install photofresco --marketplace photofresco/photofresco-agentAntigravity (CLI):
agy plugin install https://github.com/photofresco/photofresco-agentDevin (CLI; or Customize → Plugins → Add plugin → From repository in the app):
devin plugins install photofresco/photofresco-agentKiro: 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).
Python, Rust, Ruby, PHP, .NET, Java and Go clients are maintained separately in photofresco/photofresco-sdks. They use the same local connector and user permissions. The language clients and their generator are not part of this plugin or the npm connector package.
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-agentRemove 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).
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/PhotoFresco
photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
--export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stopconnect 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.
| Command | What it does |
|---|---|
connect | Start the connector if needed, open PhotoFresco and pair (you click Allow) |
status | Connector, window, session, permissions and granted folders |
request-access <list> | Ask for more permissions (read,edit,export,external-write,spend) |
documents, attach <id> | List open documents; target another one |
open <file> | Open an image from a granted folder in a new tab |
run <workflow.json> | Run a workflow (or --action <id>) with --open, --input and --export |
export <file> | Export the document (PNG, PSD or .pfd) into a granted folder |
exec <op> [params-json] | Run one editor operation |
ops [prefix], describe <op> | Operations this session may run, and their parameters |
outcome <request-id> | The result of an earlier request after a lost connection |
disconnect, stop | End the session; stop also closes the window and the connector |
mcp | The MCP server above |
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.
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
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).--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.Local files and channels
~/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).--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.Network
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.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.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.What the agent receives
--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.
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.
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.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add photofresco -- node /Users/you/photofresco-agent/src/bin/photofresco.js mcp --read /Users/you/Pictures --write /Users/you/Pictures/PhotoFresco{
"mcpServers": {
"photofresco": {
"args": [
"/Users/you/photofresco-agent/src/bin/photofresco.js",
"mcp",
"--read",
"/Users/you/Pictures",
"--write",
"/Users/you/Pictures/PhotoFresco"
],
"command": "node"
}
}
}code --add-mcp '{"name":"photofresco","args":["/Users/you/photofresco-agent/src/bin/photofresco.js","mcp","--read","/Users/you/Pictures","--write","/Users/you/Pictures/PhotoFresco"],"command":"node"}'[mcp_servers.photofresco]
command = "node"
args = ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/photofresco-for-ai-agents to learn what the "PhotoFresco for AI agents" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
claude mcp add photofresco -- npx -y [email protected] mcp --read ~/Pictures --write ~/Pictures/PhotoFresconpx skills add photofresco/photofresco-agentnpm install -g [email protected]This server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/photofresco-for-ai-agents)Nothing comparable is listed yet.
v0.1.2photofresco 0.1.2Release notesv0.1.0PhotoFresco agent 0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "photofresco-for-ai-agents" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.