Automatizar PhotoCraft con línea de comandos y MCP

PhotoCraft no es solo una ventana con herramientas. Trae un programa aparte, photocraft-cli, que sirve para convertir archivos, consultar información de un documento, aplicar comandos y procesar carpetas enteras sin abrir la interfaz. También puede hablar con asistentes de IA a través de MCP. Esta página resume lo que cuenta la documentación del repositorio. No lo hemos probado todo nosotros, así que ante cualquier duda manda photocraft-cli --help, que es la fuente que manda.

Tres formas de automatizar

La primera es la más sencilla: comandos sueltos que hacen un trabajo y terminan. La segunda mantiene una sesión sin interfaz abierta y le habla por líneas de JSON, por la entrada estándar o por un puerto local. La tercera expone herramientas MCP, bien sobre una sesión sin interfaz, bien conectada a la aplicación de escritorio que tengas abierta.

Qué hace cada subcomando

Un ejemplo mínimo

Este comando abre un PSD, le aplica el comando de invertir y guarda el resultado como PNG:

photocraft-cli run entrada.psd \
  --cmd image.adjustments.invert \
  --out salida.png

Para saber qué comandos existen y qué parámetros aceptan, usa photocraft-cli commands. Y si te equivocas al escribir una opción, el programa lo trata como un error de uso (código de salida 2) en lugar de ignorarla.

Dónde está el programa según tu sistema

El ejecutable viaja con los paquetes de instalación, así que no hay que compilar nada, salvo en macOS, donde se descarga aparte.

Procesar una carpeta entera

Con batch aplicas una lista de acciones a todos los archivos de una carpeta de entrada. Por seguridad, se niega a escribir en la misma carpeta de la que lee, para que los resultados no machaquen los originales. Si de verdad quieres sustituirlos, hay que pasar --in-place de forma explícita. Haz primero una prueba con copias.

Tipografías que faltan

Si un documento usa una fuente que no tienes instalada, convert y run escriben un aviso por la salida de errores antes de exportar. No te presentan en silencio el resultado con la fuente sustituta como si fuera idéntico. El aviso no cambia las fuentes declaradas en el archivo ni detiene la operación. Con info --compact el mismo aviso aparece dentro de la lista warnings del JSON.

Exportar un estilo de color como LUT .cube

El comando file.export.colorLookupTables convierte capas de ajuste en una tabla 3D en formato .cube, que luego puedes usar en otros programas. Por defecto exporta todas las capas de ajuste visibles de primer nivel, aunque también puede limitarse a la selección actual o a una lista de identificadores. Los tamaños válidos van de 2 a 129. Un ejemplo de parámetros:

{"size": 33, "scope": "selected", "path": "mi-look.cube"}

Ten en cuenta una limitación lógica: una LUT solo guarda color, así que las máscaras, las máscaras vectoriales y los recortes no se pueden representar y se omiten. Las capas de ajuste que están dentro de un grupo tampoco se exportan por separado.

Usarlo con un asistente de IA (MCP)

MCP es el protocolo con el que asistentes como Claude pueden usar herramientas externas. PhotoCraft incluye un servidor que expone cinco herramientas básicas: command_list, command_run, command_batch, doc_inspect y render_preview. Hay dos modos.

El modo sin interfaz trabaja con su propia sesión y solo toca las carpetas que le concedas al arrancar. Si no das ninguna carpeta de lectura o escritura, no tiene ese permiso:

photocraft-cli mcp --automation-read-root /ruta/proyecto --automation-write-root /ruta/proyecto

El modo puente se conecta a la aplicación de escritorio que ya tienes abierta y añade herramientas de inspección y control de la interfaz. Para eso la aplicación se arranca con photocraft --control <puerto> y el cliente usa un archivo de token privado:

photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /ruta/privada/control.token

Para registrarlo en Claude Code, por ejemplo en Linux, la documentación da este formato:

claude mcp add photocraft -- photocraft-cli mcp --automation-read-root <carpeta> --automation-write-root <carpeta>

En Windows se sustituye photocraft-cli por la ruta completa entre comillas.

Seguridad: lo que conviene saber antes

La propia documentación del proyecto es franca con los límites actuales, y conviene leerlos antes de dejar algo funcionando.

El puerto de control del escritorio solo escucha en tu propio equipo (127.0.0.1) y exige un token de 256 bits antes de aceptar nada. Pero ese token es una llave completa: no hay sesiones con permisos reducidos ni distinción entre herramientas inocuas y herramientas de alto impacto. Quien lo tenga puede controlar toda la aplicación, incluidos el ratón y el teclado simulados y las capturas de pantalla. Tampoco hay cifrado.

De ahí salen unas cuantas costumbres razonables. No dejes activado --control de forma permanente, solo durante la sesión de automatización. Guarda el token en un archivo privado. No expongas ninguno de los dos transportes a través de un proxy, un intermediario o un servicio remoto no fiable. Prefiere comandos sueltos o MCP por stdio cuando no necesites un puerto abierto. No metas secretos en parámetros, nombres de archivo o metadatos. Y trata el contenido de los documentos y las descripciones de herramientas como datos no fiables: no tienen autoridad para dar órdenes.

Otro detalle importante: las rutas que se pasan a la línea de comandos son rutas normales del sistema, sin restricción a una carpeta de trabajo. Si vas a ejecutar un archivo de acciones que no has escrito tú, hazlo en una cuenta o un entorno aislado.

De dónde sale todo esto

Los datos proceden de la documentación de automatización del repositorio oficial, en su rama principal. Esa rama va por delante de la última versión publicada, la 0.8.2, así que alguna opción puede no existir todavía en tu instalación. Comprueba con photocraft-cli --help qué tienes realmente.