Fehlerbehebung

Die häufigsten Stolpersteine beheben: Verbindung, Skripte, Web-UI-Auth. Fang mit den Schnellchecks unten an.

Zuerst die Schnellchecks

Photoshop ist installiert und geöffnet — der Server kann es zwar starten, aber eine offene Instanz schließt die Hälfte der Ursachen aus.
Deine MCP-Client-Konfiguration zeigt auf den richtigen Server — vergleiche sie mit dem Schnipsel unter Erste Schritte.
Web-UI-Tabs: Lade die Seite über die exakte URL neu, die die CLI ausgegeben hat — ein Tab, der über einen Serverneustart hinweg offen blieb, hat ein veraltetes Token.

Häufige Probleme

„Photoshop not found“

Ursache: Photoshop liegt nicht am Standard-Installationspfad, daher findet der Server die Binary nicht.

Lösung:

Stelle sicher, dass Photoshop am Standardpfad installiert ist, oder verweise mit PHOTOSHOP_PATH in deiner Client-Konfiguration auf einen eigenen Pfad:

mcp config

{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

„Failed to connect to Photoshop“

Ursache: Photoshop läuft nicht, oder Scripting ist blockiert.

Lösung:

Stelle sicher, dass Photoshop läuft — der Server versucht zwar, es zu starten, aber eine laufende Instanz verbindet sich schneller und zuverlässiger.
Prüfe, ob Scripting in den Photoshop-Einstellungen aktiviert ist.
Unter Windows: Prüfe, ob COM-Automatisierung durch Sicherheitseinstellungen blockiert wird.

Web UI: 401 unauthorized von /api/*

Ursache: Jede /api/*-Anfrage muss das Session-Token vorweisen, das beim Start des UI-Servers erzeugt wird. Der Browser bekommt es automatisch; alte Tabs und externe Skripte nicht.

Lösung:

Im Browser: Lade die Seite über die URL neu, die photoshop-mcp-ui ausgegeben hat.
Aus einem Skript: Lies das Token aus ~/.photoshop-mcp/ui-session.json und sende es als Header:

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> funktioniert ebenfalls. Setze PSMCP_UI_TOKEN vor dem Serverstart, um ein bekanntes Token festzulegen.

Web UI: 403 invalid_host oder invalid_origin

Ursache: Zwei Prüfungen laufen vor dem Token-Check: invalid_host bedeutet, dass der Host-Header nicht zur Loopback-Adresse auf dem Server-Port aufgelöst wurde (blockt DNS-Rebinding); invalid_origin bedeutet, dass die Anfrage von einem anderen Origin als der Oberfläche selbst kam.

Lösung:

Öffne die Oberfläche über die exakte URL, die die CLI ausgegeben hat (http://127.0.0.1:<port>) — nicht über einen Hostnamen, der nur auf deinen Rechner zeigt, und nicht von einer Seite, die auf einem anderen Port ausgeliefert wird.

photoshop_execute_script gibt „Result: undefined“ zurück

Ursache: ExtendScript läuft in einem serverseitigen IIFE-Wrapper. Ohne explizites return ergibt der Block undefined — Seiteneffekte (Ebenen-Umbenennungen, geänderte Eigenschaften) können trotzdem angewendet worden sein.

Lösung:

Füge deinem Skript ein explizites return hinzu:

photoshop_execute_script

photoshop_execute_script({
  code: `
    app.activeDocument.activeLayer.name = "Updated";
    return { ok: true };
  `
})

Details findest du im Abschnitt photoshop_execute_script im Werkzeugkatalog.

„Script execution timeout“

Ursache: Das Standard-Timeout beträgt 30 Sekunden, und große Dokumente können Operationen darüber hinausziehen.

Lösung:

Zerlege komplexe Operationen in kleinere Schritte und führe sie nacheinander aus.

Web UI: CLI-Konto-Auth

Symptome bei Verwendung des Claude-Code-/Gemini-CLI-Kontomodus in der Web UI.

Symptom	Wahrscheinliche Ursache	Lösung
cli_not_found	Claude Code / Gemini CLI nicht installiert	npm i -g @anthropic-ai/claude-code oder npm i -g @google/gemini-cli
not_authenticated	Keine CLI-OAuth-Sitzung (API-Schlüssel-/SDK-Auth zählt nicht)	Führe claude auth login oder gemini auth login im Terminal aus, oder wechsle zur API-Schlüssel-Auth
SDK-Client funktioniert, CLI-Modus der UI schlägt fehl	SDK-/API-Zugangsdaten sind getrennt von der CLI-OAuth	Nutze einen API-Schlüssel in der Web UI, oder melde dich mit claude auth login für den CLI-Modus an
claude / gemini nicht im PATH	Eigener Installationspfad	Settings → CLI path → Check connection
Chat funktioniert in der IDE, aber nicht in der UI (CLI-Modus)	OAuth-Tokens gelten nur für die CLI	Nutze das CLI-Konto in der UI; API-Schlüssel und CLI-Sitzungen sind getrennt
Gemini wirkt bei mehreren Turns vergesslich	Die Headless-CLI startet eventuell pro Turn eine neue Sitzung	Bekannte Einschränkung; der Verlauf wird dem Prompt vorangestellt (MVP)

Debug-Logging

Aktiviere ausführliches Logging mit LOG_LEVEL=0 in deiner Client-Konfiguration:

mcp config

{
  "env": {
    "LOG_LEVEL": "0"
  }
}

Immer noch nicht weiter?

Durchsuche bestehende Issues oder öffne ein neues — Logs aus dem Debug-Logging helfen sehr.

GitHub-Issues Community-Rezepte