Photoshop MCP

Solución de problemas

Resuelve los tropiezos más comunes: conexión, scripts, autenticación de la interfaz web. Empieza por las comprobaciones rápidas de abajo.

Comprobaciones rápidas primero
  • Photoshop está instalado y abierto: el servidor puede lanzarlo, pero una instancia ya abierta descarta la mitad de las causas.
  • La configuración de tu cliente MCP apunta al servidor correcto: compárala con el fragmento de Primeros pasos.
  • Pestañas de la interfaz web: recarga desde la URL exacta que mostró el CLI; una pestaña que sigue abierta tras reiniciar el servidor lleva un token caducado.

Problemas comunes

«Photoshop not found»

Causa: Photoshop no está en la ubicación de instalación predeterminada, así que el servidor no encuentra el binario.

Solución:

  • Asegúrate de que Photoshop esté instalado en la ubicación predeterminada, o indica al servidor una ruta personalizada con PHOTOSHOP_PATH en la configuración de tu cliente:
mcp config
{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

«Failed to connect to Photoshop»

Causa: Photoshop no se está ejecutando, o el scripting está bloqueado.

Solución:

  • Asegúrate de que Photoshop esté en ejecución: el servidor intenta lanzarlo, pero una instancia ya abierta conecta más rápido y de forma más fiable.
  • Comprueba que el scripting esté activado en las preferencias de Photoshop.
  • En Windows, verifica que la automatización COM no esté bloqueada por la configuración de seguridad.

Interfaz web: 401 unauthorized desde /api/*

Causa: Cada petición a /api/* debe presentar el token de sesión que se genera al arrancar el servidor de la interfaz. El navegador lo obtiene automáticamente; las pestañas antiguas y los scripts externos no.

Solución:

  • En el navegador: recarga la página desde la URL que mostró photoshop-mcp-ui.
  • Desde un script: lee el token de ~/.photoshop-mcp/ui-session.json y envíalo como cabecera:
terminal
TOKEN=$(node -p "require('$HOME/.photoshop-mcp/ui-session.json').token")
curl -H "x-psmcp-token: $TOKEN" http://127.0.0.1:5174/api/status

Authorization: Bearer <token> también funciona. Define PSMCP_UI_TOKEN antes de arrancar el servidor para fijar un token conocido.

Interfaz web: 403 invalid_host o invalid_origin

Causa: Dos protecciones se ejecutan antes de la comprobación del token: invalid_host significa que la cabecera Host no resolvía a la dirección de loopback en el puerto del servidor (esto bloquea el DNS rebinding); invalid_origin significa que la petición llegó desde un origen distinto al de la propia interfaz.

Solución:

  • Abre la interfaz desde la URL exacta que mostró el CLI (http://127.0.0.1:<port>), no desde un hostname que simplemente apunte a tu máquina ni desde una página servida en otro puerto.

photoshop_execute_script devuelve «Result: undefined»

Causa: ExtendScript se ejecuta dentro de un contenedor IIFE en el servidor. Sin un return explícito, el bloque se evalúa como undefined; los efectos secundarios (renombrar capas, cambiar propiedades) pueden haberse aplicado igualmente.

Solución:

  • Añade un return explícito a tu script:
photoshop_execute_script
photoshop_execute_script({
  code: `
    app.activeDocument.activeLayer.name = "Updated";
    return { ok: true };
  `
})

Consulta la sección de photoshop_execute_script en Herramientas disponibles para más detalles.

«Script execution timeout»

Causa: El tiempo de espera predeterminado es de 30 segundos, y los documentos grandes pueden hacer que las operaciones lo superen.

Solución:

  • Divide las operaciones complejas en pasos más pequeños y ejecútalos en secuencia.

Interfaz web: autenticación con cuenta CLI

Síntomas al usar el modo de cuenta de Claude Code / Gemini CLI en la interfaz web.

SíntomaCausa probableSolución
cli_not_foundClaude Code / Gemini CLI no está instaladonpm i -g @anthropic-ai/claude-code o npm i -g @google/gemini-cli
not_authenticatedNo hay sesión OAuth del CLI (la autenticación con clave de API / SDK no cuenta)Ejecuta claude auth login o gemini auth login en la terminal, o cambia a autenticación con clave de API
El cliente SDK funciona, pero el modo CLI de la interfaz fallaLas credenciales del SDK/API son independientes del OAuth del CLIUsa una clave de API en la interfaz web, o inicia sesión con claude auth login para el modo CLI
claude / gemini no está en el PATHUbicación de instalación personalizadaSettings → CLI path → Check connection
El chat funciona en el IDE pero no en la interfaz (modo CLI)Los tokens OAuth son solo del CLIUsa la cuenta CLI en la interfaz; las claves de API y las sesiones del CLI son independientes
Gemini parece olvidadizo en multiturnoEl CLI headless puede iniciar una sesión nueva en cada turnoLimitación conocida; el historial se antepone al prompt (MVP)

Registro de depuración

Activa el registro detallado con LOG_LEVEL=0 en la configuración de tu cliente:

mcp config
{
  "env": {
    "LOG_LEVEL": "0"
  }
}

¿Sigues atascado?

Busca en los issues existentes o abre uno nuevo: los registros capturados con el registro de depuración ayudan mucho.

Issues de GitHubRecetas de la comunidad