PhotoFresco

Permite que los agentes de IA editen imágenes en una ventana de PhotoFresco que tú apruebas: capas, máscaras, vistas previas y exportación.

GitHubPrueba este MCPPatrocinado

Documentación

PhotoFresco para agentes de IA

Permite que los agentes de IA editen imágenes en una ventana de PhotoFresco que tú apruebas: capas, máscaras, vistas previas y exportación.

PhotoFresco es un editor de imágenes gratuito, de clase Photoshop, que se ejecuta en tu navegador: capas, máscaras, capas de ajuste, selecciones, pinceles, importación y exportación de PSD, e historial de deshacer completo. Este repositorio conecta agentes de IA a él. Un agente (Claude, Cursor, VS Code, Codex o cualquier cliente MCP, o un script a través de la línea de comandos) controla una ventana de PhotoFresco en tu propia computadora. Tú observas cada cambio, permites la conexión, eliges qué puede hacer el agente y puedes pausarlo o detenerlo en cualquier momento. La edición en sí ocurre en el editor, por lo que cada cambio queda en su Historial y se puede deshacer como si fuera tuyo.

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

La grabación anterior es una sesión real: un cliente MCP llamando a este servidor contra el editor, capturada sin interfaz gráfica. Categoría: Diseño / edición de imágenes.

Qué contiene este repositorio:

Servidor MCP (photofresco mcp): una herramienta por operación del editor, vistas previas como imágenes, exportaciones como archivos o recursos. Guía: MCP.md.
Habilidad de agente (skills/photofresco): enseña a un agente cuándo y cómo usar PhotoFresco correctamente.
Línea de comandos (photofresco <command>): abrir, ejecutar flujos de trabajo guardados, exportar, detener. Guía: CLI.md.
Conector local (la biblioteca que comparten los otros tres): CONNECTOR.md.

El editor en sí no está en este repositorio; el conector lo abre en photofresco.com.

Requisitos

Node.js 22 o más reciente.
Un navegador basado en Chromium instalado: Google Chrome, Microsoft Edge o Chromium 120 o más reciente. No se descarga nada. Apunta --browser (o PHOTOFRESCO_BROWSER) a otro si es necesario.
macOS está verificado; Windows y Linux están implementados pero aún no verificados.

Configura tu agente

Un clic (Cursor, VS Code, LM Studio):

Cada botón pide a la aplicación que agregue el servidor photofresco, iniciado con npx desde el archivo fuente de GitHub de la versión 0.1.0 (commit 328cfaf; nada proviene del registro npm). No otorga carpetas: agrega los argumentos --read y --write después de mcp en la configuración MCP de la aplicación para permitir que el agente abra y guarde archivos.

De lo contrario, agrega el servidor a la configuración MCP de tu cliente a continuación. Elige las carpetas desde las que el agente puede abrir archivos (--read) y en las que puede guardar exportaciones (--write). Sin ellas, el agente aún puede editar y previsualizar, pero no puede tocar tus archivos.

Publicación npm pendiente. El paquete npm photofresco se publica a mediados de octubre de 2026, por lo que los comandos npx -y photofresco@0.1.0 a continuación aún no funcionan. Hasta entonces, coloca --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco (la misma versión, desde GitHub) en lugar de photofresco@0.1.0, instala el plugin, o ejecuta desde un clon de este repositorio como se indica a continuación: node /path/to/photofresco-agent/src/bin/photofresco.js en lugar de la parte npx -y photofresco@0.1.0 (no se necesita npm install).

Desde un clon (funciona hoy; el SDK de MCP está incluido, por lo que no hay nada que instalar):

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

Luego agrega esta entrada a cualquier cliente que lea mcpServers (Claude Desktop, Cursor, Windsurf, Kiro y la mayoría de los demás), con tu propia carpeta de inicio en lugar de /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 (Configuración → Desarrollador → Editar configuración):

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

Cursor: ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (un proyecto), con la misma entrada mcpServers que Claude Desktop.

VS Code: .vscode/mcp.json en un espacio de trabajo, o MCP: Abrir configuración de usuario para todos ellos:

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

Windsurf (Cascade): la misma entrada mcpServers que Claude Desktop, en mcp_config.json (Cascade → MCPs → Abrir archivo de configuración MCP).

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 en un proyecto, o ~/.config/opencode/opencode.json para todos ellos (desde un clon, como se indicó anteriormente):

{
  "$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: la entrada mcpServers del clon anterior, en ~/.kiro/settings/mcp.json (todos los espacios de trabajo) o .kiro/settings/mcp.json (un espacio de trabajo).

Cline: dale a Cline este repositorio; llms-install.md lo guía a través de la instalación, conexión y detención.

El servidor se prueba con el cliente oficial de MCP TypeScript sobre stdio; estas entradas siguen el formato stdio documentado de cada aplicación. Opciones:

Opción	Significado
`--read <folder>`	El agente puede abrir archivos de imagen desde esta carpeta (repetible)
`--write <folder>`	El agente puede guardar exportaciones en esta carpeta y nuevas subcarpetas (repetible)
`--overwrite`	Las exportaciones pueden reemplazar archivos existentes en carpetas `--write` (el agente también debe solicitarlo)
`--tools <groups>`	Qué operaciones se listan como herramientas: `essentials` (predeterminado, como máximo 40 herramientas), `all`, o una lista separada por comas de grupos (MCP.md)
`--profile <folder>`	Carpeta de perfil del navegador, o `ephemeral` para una desechable
`--browser <path>`	Navegador basado en Chromium a usar (igual que `PHOTOFRESCO_BROWSER`)

MCP Bundle (Claude Desktop y otras aplicaciones que instalan archivos .mcpb): node scripts/build-mcpb.mjs construye dist/photofresco-mcp-0.1.0.mcpb y su SHA-256 desde este repositorio (reproducible con la misma versión de Node.js). El bundle inicia el mismo servidor y, como un plugin, no otorga carpetas. Cada lanzamiento de GitHub adjunta este archivo; su SHA-256 es el fileSha256 en server.json, la entrada del Registro Oficial de MCP.

Docker (para registros de MCP que verifican servidores en un contenedor): docker build -t photofresco-mcp . luego docker run -i --rm photofresco-mcp ejecuta el servidor sobre stdio. La imagen no tiene navegador, por lo que solo lista herramientas; photofresco_connect falla allí con browser_not_found. Edita imágenes con una instalación local como se indicó anteriormente.

Cómo transcurre una sesión

El agente llama a photofresco_connect. PhotoFresco se abre en su propia ventana con un código de conexión; el agente te dice el mismo código. Verifícalo y haz clic en Permitir.
La sesión comienza sin permisos. El agente solicita lo que necesita (Leer, Editar, Exportar; Enviar y Gastar solo para IA en la nube y de pago) y tú eliges en el diálogo Permisos. Las herramientas de edición aparecen para el agente a medida que las otorgas.
El agente edita con una herramienta por operación del editor, mira las vistas previas y deshace lo que no le gusta. Editar tú mismo pausa al agente hasta que presionas Reanudar. Detener finaliza la sesión; también lo hace cerrar la ventana.

Nada se abre hasta que el agente llama a photofresco_connect: iniciar el servidor y listar sus herramientas no inicia ningún navegador.

Instalar como plugin

Este repositorio también es un plugin para Claude Code, Codex, Cursor, Gemini CLI, Hermes Agent, OpenClaw, Antigravity, Devin y Kiro: una instalación agrega el servidor MCP y la Habilidad de agente. El cliente copia el repositorio e inicia el servidor con node <plugin folder>/src/bin/photofresco.js mcp; no se descarga nada de npm, porque el SDK de MCP está incluido legible en vendor/. Node.js 22 o más reciente debe estar en tu PATH.

Una instalación de plugin otorga ninguna carpeta: el agente edita la imagen abierta en la ventana de PhotoFresco, y tú abres y guardas archivos allí tú mismo. Para acceso del agente a archivos, configura el servidor con --read y --write como se indicó anteriormente en su lugar.

Claude Code (en una sesión; la tercera línea hace ambos pasos en uno en Claude Code 2.1.275 o posterior):

/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 pasa a las extensiones solo unas pocas variables de entorno, por lo que PHOTOFRESCO_BROWSER no llega a esta; con un navegador fuera de las ubicaciones estándar, usa la configuración MCP anterior.

Cursor: instala PhotoFresco desde Personalizar una vez que esté listado, o copia este repositorio en ~/.cursor/plugins/local/photofresco y recarga la ventana.

Hermes Agent (una versión con soporte de Agent Plugins, que tiene hermes plugins validate). Los plugins se instalan deshabilitados; habilitarlos carga el servidor y la habilidad en la próxima sesión:

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

OpenClaw (te pide revisar el código fuente, luego aceptar el servidor MCP y la habilidad del plugin):

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

Antigravity (CLI):

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

Devin (CLI; o Personalizar → Plugins → Agregar plugin → Desde repositorio en la aplicación):

devin plugins install photofresco/photofresco-agent

Kiro: Powers → Agregar Custom Power → Importar power desde GitHub, luego https://github.com/photofresco/photofresco-agent.

Los manifiestos son .claude-plugin/ (Claude Code, también leído por Devin), plugin.json con mcp.json (el estándar Agent Plugins, usado por Codex, Hermes Agent y Kiro), .cursor-plugin/plugin.json (Cursor y OpenClaw, que lee .mcp.json a través de él), gemini-extension.json (Gemini CLI), mcp_config.json (Antigravity) y openclaw.plugin.json (metadatos de OpenClaw y ClawHub).

Habilidad de agente

La Habilidad de agente en skills/photofresco enseña a agentes capaces de habilidades (Claude Code, Codex, Cursor y otros) cuándo usar PhotoFresco, cómo conectarse y solicitar permisos, el bucle orientar → editar → previsualizar → deshacer, flujos de trabajo, exportaciones, cada código de error y la línea de comandos. No configura el servidor MCP; configúralo como se indicó anteriormente. Instálala con el CLI skills en el proyecto actual (-g para tu usuario):

npx skills add photofresco/photofresco-agent

Elimínala con npx skills remove photofresco. La referencia de operaciones es la propia lista de herramientas del servidor (photofresco_list_tool_groups, o photofresco ops en la línea de comandos).

Línea de comandos

El mismo paquete instala un comando photofresco para scripts y agentes que tienen un shell pero no un cliente MCP. Controla el mismo tipo de ventana aprobada a través de un proceso de conector en segundo plano. Hasta que el paquete npm se publique (mediados de octubre de 2026), ejecútalo desde un clon en lugar de npm install -g: alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js".

npm install -g photofresco@0.1.0
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 stop

connect abre PhotoFresco e imprime un código de conexión; verifica que la ventana muestre el mismo código, haz clic en Permitir y elige los permisos. run abre la imagen en una nueva pestaña, ejecuta un flujo de trabajo guardado (el archivo portátil que exporta el panel de Acciones del editor) y escribe la exportación solo después de que su SHA-256 coincida. stop finaliza la sesión, cierra la ventana y detiene el proceso del conector.

Comando	Qué hace
`connect`	Inicia el conector si es necesario, abre PhotoFresco y empareja (haces clic en Permitir)
`status`	Conector, ventana, sesión, permisos y carpetas otorgadas
`request-access <list>`	Solicita más permisos (`read,edit,export,external-write,spend`)
`documents`, `attach <id>`	Lista documentos abiertos; apunta a otro
`open <file>`	Abre una imagen desde una carpeta otorgada en una nueva pestaña
`run <workflow.json>`	Ejecuta un flujo de trabajo (o `--action <id>`) con `--open`, `--input` y `--export`
`export <file>`	Exporta el documento (PNG, PSD o `.pfd`) a una carpeta otorgada
`exec <op> [params-json]`	Ejecuta una operación del editor
`ops [prefix]`, `describe <op>`	Operaciones que esta sesión puede ejecutar, y sus parámetros
`outcome <request-id>`	El resultado de una solicitud anterior después de una conexión perdida
`disconnect`, `stop`	Finaliza la sesión; `stop` también cierra la ventana y el conector
`mcp`	El servidor MCP anterior

Cada comando toma --json (un objeto en stdout, también en caso de fallo) y devuelve un código de salida documentado (0 éxito, 2 uso, 3 no conectado, 4 ruta rechazada, 5 rechazado por el editor, 8 cancelado, 75 aún esperándote). Referencia completa: CLI.md.

Qué ejecuta, envía y obtiene

Observado en macOS con Chrome for Testing 145 contra una compilación local del editor, registrado en DISCLOSURE.md con cada detalle; cualquier cosa no observada está marcada allí.

Ejecuciones

Un proceso de Node.js: el servidor MCP que tu cliente inicia (termina cuando el cliente lo cierra), o cada comando photofresco más un proceso conector en segundo plano por carpeta de datos (termina en photofresco stop, cuando cierras su ventana, o después de un minuto sin ventana ni comando).
Un árbol de procesos del navegador, solo cuando el agente se conecta: tu Chrome, Edge o Chromium instalado, iniciado con un perfil dedicado y su tubería de DevTools (--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions). Muestra una ventana normal y visible (la demostración anterior se grabó sin interfaz gráfica). Tus perfiles de navegador cotidianos nunca se abren, leen ni adjuntan.
Sin otros programas, comandos de shell, instaladores, servicios, elementos de inicio o extensiones.

Archivos y canales locales

Carpeta de datos: ~/Library/Application Support/PhotoFresco Connector (macOS), %LOCALAPPDATA%\PhotoFresco Connector (Windows) o ~/.local/share/photofresco-connector (Linux). Contiene el perfil del navegador (cookies e inicio de sesión si inicias sesión allí, caché, almacenamiento local y autoguardado del editor), un archivo de bloqueo y, para la línea de comandos, cli/ con un socket Unix (0600 en una carpeta 0700), una clave aleatoria por inicio y connector.log (eventos sin secretos: rutas de carpetas concedidas, rutas, tamaños y SHA-256 de archivos leídos o escritos; sin claves, contenidos de archivos ni píxeles; como máximo 4 MiB).
Tus archivos: solo lectura dentro de carpetas --read cuando el agente abre un archivo (como máximo 32 MiB), y solo escritura dentro de carpetas --write cuando exporta, a través de un archivo temporal renombrado en su lugar después de que su SHA-256 coincidiera. Los archivos existentes se reemplazan solo con --overwrite y el agente lo solicita.
Sin puerto de red en escucha. El navegador se controla a través de su tubería privada; la línea de comandos usa el socket local. Observado: sin socket TCP en el servidor o el proceso conector.

Red

El conector, el servidor MCP y la línea de comandos no realizan solicitudes de red por sí mismos. npx/npm install descarga el paquete del registro npm primero (los botones de un clic, hasta el lanzamiento de npm, descargan el archivo fuente de este repositorio desde GitHub en su lugar); una instalación de complemento hace que el cliente del agente copie este repositorio (desde GitHub), y al iniciar el servidor no se descarga nada.
El navegador abre https://photofresco.com/app/?pf_ref=mcp (o cli), una etiqueta no secreta para atribución, y carga el editor como una visita normal. Debido a que el navegador está automatizado, no muestra anuncios de terceros.
La ventana del conector comienza con la grabación de sesión desactivada. El editor reconoce la ventana que el conector abrió (un canal privado que ningún enlace o sitio web puede configurar) y la inicia con nada permitido en Datos y privacidad, por lo que nada de tus archivos se sube: sin grabación de sesión, sin diagnósticos, sin copia de los archivos que el agente abre y sin eventos de uso. Observado: sin solicitud de grabación o telemetría desde la conexión hasta el final de la sesión, incluso después de que el agente importó una foto. Permitir al agente activa solo Agentes externos allí.
La grabación permanece desactivada a menos que actives la grabación en Datos y privacidad en esa ventana. Desde entonces envía a PhotoFresco los eventos de entrada, comandos del editor, nombres de documentos, texto escrito (los campos de contraseña y correo electrónico están enmascarados) y una copia de cada imagen abierta en la ventana, incluidos los archivos que el agente abre a través del conector (como máximo 16 MiB cada uno, 6 por carga de página), además de diagnósticos (errores, eventos de funciones, rendimiento, un perfil de dispositivo) y eventos de uso seguros para la privacidad (referral, open, edit, export, marcados automated; sin nombres de archivos ni píxeles). Una visita normal a photofresco.com, no abierta por el conector, tiene la grabación activada por defecto.
El tráfico de fondo propio del navegador (actualizaciones, navegación segura) sigue sus valores predeterminados; no medido. Las solicitudes de terceros del sitio de producción no se verificaron.

Lo que recibe el agente

Solo lo que tus permisos permiten: estado de la sesión, estado del documento, resultados de operaciones, vistas previas (píxeles) y archivos exportados. Todo lo que el agente recibe va al proveedor de modelos de ese agente, bajo la política de ese proveedor.
Las funciones de IA de pago se ejecutan solo con el permiso de Gasto y el presupuesto de crédito que establezcas; enviar datos a los servicios de PhotoFresco (documentos en la nube, IA) necesita el permiso de Envío.
La ventana te muestra quién se conecta: el nombre que el cliente MCP envía en su protocolo de enlace (" vía MCP"), o --client en la línea de comandos ("Terminal vía CLI" por defecto).

Tú mantienes el control: cada conexión necesita tu Permiso, una sesión comienza sin permisos, y Detener, cerrar la ventana, recargar o salir del editor la termina. Cerrar el conector cierra su ventana.

Desinstalación

Elimina la entrada MCP de la configuración de tu cliente (o ejecuta photofresco stop y npm uninstall -g photofresco), o elimina el complemento (/plugin uninstall photofresco@photofresco en 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, o Personalizar en Cursor y el panel Powers en Kiro). Elimina la habilidad con npx skills remove photofresco, y borra la carpeta de datos anterior. Nada más está instalado.

Soporte

Preguntas y errores: Problemas de GitHub o hello@photofresco.com.
Documentación: Usar PhotoFresco con agentes de IA.
Política de privacidad: photofresco.com/docs/privacy.
Términos de servicio: photofresco.com/docs/terms.
Sitio web: photofresco.com.

Licencia

Este repositorio (el servidor MCP, la línea de comandos, el conector y la habilidad) se publica bajo la Licencia MIT. El editor PhotoFresco y el servicio photofresco.com no forman parte de él.