Fehlerbehebung

Diese Seite behandelt häufige Probleme in Bezug auf beide Docker- als auch npm-Distributionen. Probleme, die nur auf eine Distribution zutreffen, sind entsprechend gekennzeichnet.

Server startet nicht

• Stellen Sie sicher, dass Docker läuft (Docker-Distribution) oder dass Chromium installiert ist (npm-Distribution – siehe Chromium-Installation)
• Überprüfen Sie, ob Ihre Anmeldedaten korrekt sind: entweder Ihr AXE_API_KEY oder Ihr AXE_ACCESS_TOKEN, aber nicht beide (der Server schlägt beim Start fehl, wenn beide gesetzt sind)
• Prüfen Sie, ob Sie Zugriff auf den axe MCP-Server haben (kontaktieren Sie den Support, falls erforderlich)

Scan-Zeitüberschreitungen

• Erhöhen Sie BROWSER_TIMEOUT_MS für komplexe Seiten
• Stellen Sie sicher, dass die Ziel-URL von Ihrem Netzwerk aus zugänglich ist
• Prüfen Sie auf Netzwerkverbindungsprobleme

Der Scan des lokalen Entwicklungsservers schlägt mit ERR_CONNECTION_REFUSEDfehl

Dies gilt für die Docker-Distribution – bei der npm-Distribution läuft der Server direkt auf Ihrem Host und kann localhost-Dienste normal erreichen.

Wenn das analyze-Tool beim Versuch, einen lokal laufenden Entwicklungsserver zu scannen, mit einem net::ERR_CONNECTION_REFUSED-Fehler fehlschlägt, liegt das wahrscheinlich daran, dass der axe MCP Server in einem Docker-Container läuft und keine Dienste erreichen kann, die nur an localhost (d.h. 127.0.0.1) auf Ihrem Host gebunden sind.

Beispiel für einen Fehler:

net::ERR_CONNECTION_REFUSED at http://192.168.65.2:5173/

Lösung: Starten Sie Ihren Entwicklungsserver mit dem gesetzten --host-Flag auf 0.0.0.0, sodass er auf allen Netzwerkschnittstellen lauscht und aus dem Docker-Container erreichbar ist:

# Vite
npm run dev -- --host=0.0.0.0

# Webpack (webpack-dev-server)
npm run dev -- --host=0.0.0.0

Docker-Probleme

• Stellen Sie sicher, dass der Docker-Daemon läuft
• Überprüfen Sie die Docker-Berechtigungen
• Überprüfen Sie die Netzwerkkonnektivität für Docker-Image-Downloads
• Stellen Sie sicher, dass Docker über genügend Speicher verfügt, indem Sie einen docker system prune ausführen

Chromium-Installation (npm)

Dieser Abschnitt gilt für die npm-Distribution. Die Docker-Distribution bündelt ihren eigenen Browser, sodass Docker-Benutzer Chromium nicht installieren müssen und von den hier beschriebenen Fehlern nicht betroffen sind.

Was der Fehler bedeutet

Der axe MCP Server führt Barrierefreiheitsüberprüfungen durch, indem er einen echten Browser über Playwright steuert. Bei der npm-Distribution muss dieser Browser — Chromium — auf Ihrem Host installiert sein. Wenn es fehlt oder wenn die installierte Version nicht der Chromium-Version entspricht, die Playwright in der gelieferten Serverversion erwartet, schlägt der Server beim Starten (oder beim ersten Scan) mit einem Fehler fehl, der darauf hinweist, dass Chromium nicht gestartet werden konnte.

Dies ist bei einer Neuinstallation zu erwarten und leicht zu beheben.

Standardlösung

Installieren Sie die Chromium-Version, die der Playwright-Version entspricht, die der axe MCP Server liefert — derzeit 1.60.0. Fixieren Sie Playwright auf diese Version, sodass ein nackter npx playwright nicht zu einer neueren Veröffentlichung führt, die eine Chromium-Version hat, die der Server nicht unterstützt:

npx playwright@1.60.0 install chromium

Starten Sie dann den MCP-Server (oder Ihren MCP-Client) neu und versuchen Sie es erneut.

Nachverfolgung für Linux

Unter Linux hängt Chromium auch von mehreren Systembibliotheken ab, die eventuell nicht vorhanden sind. Falls der Browser nach der Standardlösung immer noch nicht startet, installieren Sie diese Abhängigkeiten:

sudo npx playwright@1.60.0 install-deps chromium

Sie können auch beide Schritte in einem einzigen Befehl kombinieren:

sudo npx playwright@1.60.0 install --with-deps chromium

Verwenden Sie einen Browser, den Sie bereits haben

Wenn Sie bereits über eine kompatible Chrome-/Chromium-Binärdatei auf Ihrem Host verfügen, können Sie die Playwright-Installation vollständig umgehen, indem Sie die AXE_CHROME_PATH-Umgebungsvariable auf diese Binärdatei setzen. Dies ist oft die schnellste Lösung, wenn der Playwright-Download blockiert ist (eingeschränktes Netzwerk, Proxy) oder wenn die Installation von Systemabhängigkeiten keine Option ist. Siehe AXE_CHROME_PATH für Anforderungen – beachten Sie, dass das gebrandete Google Chrome stable 137+ nicht unterstützt wird und der Wert eine ausführbare Binärdatei und kein .app-Bundle sein muss.

Warum Chromium nicht gebündelt wird

Playwright fixiert eine spezifische Chromium-Revision auf jede Playwright-Version, und diese Version ändert sich mit der Zeit. Das Einbetten einer Browser-Binärdatei in das npm-Paket würde seine Größe erheblich vergrößern, das Paket an die Binärdatei einer Plattform binden und veralten, sobald Playwright seine fixierte Version aktualisiert. Die Installation von Chromium über Playwright gewährleistet stattdessen, dass Sie genau die Version erhalten, die Ihre installierte Version erwartet, für Ihre Plattform. (Die Docker-Distribution kann einen Browser einbetten, da das Image für eine einzelne, bekannte Umgebung erstellt wird.)

Erneutes Ausführen nach einem Upgrade des axe-mcp-servers

Das Upgrade von axe-mcp-server kann eine neuere Playwright-Version mit sich bringen, die eine neuere Chromium-Revision fixiert, die anders ist als die aktuell installierte. Wenn das passiert, könnten Sie denselben Startfehler erneut sehen nach einem Upgrade. Die Lösung ist dieselbe – führen Sie die Installation mit der Playwright-Version aus, die der aktualisierte Server liefert, damit Chromium übereinstimmt:

npx playwright@1.60.0 install chromium

Als Faustregel: Führen Sie diesen Befehl erneut aus – unter Verwendung der Playwright-Version der aktuellen Veröffentlichung – jedes Mal, wenn Sie axe-mcp-server aktualisieren und der Server bei der Initialisierung einen Chromium-Mismatch meldet.

Authentifizierungsfehler

API-Schlüssel

• Stellen Sie sicher, dass Ihr API-Schlüssel gültig ist und nicht abgelaufen ist
• Stellen Sie sicher, dass Ihr axe Account Portal-Abonnement den Zugriff auf den MCP-Server enthält
• Überprüfen Sie, dass der API-Schlüssel für das Produkt „axe MCP Server“ erstellt wurde
• Stellen Sie sicher, dass nur AXE_API_KEY gesetzt ist – wenn AXE_ACCESS_TOKEN ebenfalls gesetzt ist, schlägt der Server beim Start fehl
• Stellen Sie sicher, dass Ihre axe-Server-URL korrekt ist – wenn Ihre Organisation eine regionale, private Cloud oder eine vor Ort gehostete axe-Instanz verwendet, muss AXE_SERVER_URL auf die Basis-URL Ihrer Instanz gesetzt sein. Details siehe Konfigurationsreferenz.

OAuth

• Stellen Sie sicher, dass nur AXE_ACCESS_TOKEN gesetzt ist – wenn AXE_API_KEY ebenfalls gesetzt ist, schlägt der Server beim Start fehl
• Führen Sie npx @deque/axe-auth token in Ihrem Terminal aus, um zu bestätigen, dass Sie ein gültiges Token haben; wenn es mit einem Nicht-Null-Code endet, authentifizieren Sie sich erneut mit npx @deque/axe-auth login
• Stellen Sie sicher, dass Ihre axe-Server-URL korrekt ist
• Wenn Ihr Token während der Sitzung abgelaufen ist, starten Sie die MCP-Serververbindung in Ihrem Client neu (z.B. Neustrart von Claude Code, Umschalten des Servers in den Cursor-MCP-Einstellungen, oder durch direktes Klicken auf die „Neustart“-Schaltfläche von VS Code's CodeLens über dem Eintrag des axe MCP Servers in mcp.json), um ein neues Token zu erhalten
• Siehe Authentifizierung für vollständige OAuth-Fehlerbehebungsschritte

Hilfe bekommen

Wenn Sie auf Probleme stoßen, die in diesem Fehlerbehebungsabschnitt nicht behandelt werden:

1. Überprüfen Sie die Entwicklerkonsole/Logs Ihres MCP-Clients auf detaillierte Fehlermeldungen (z.B. die VS Code Developer Console, Cursor's Developer Tools oder Claude Code's --debug Ausgabe)
2. Überprüfen Sie die Serverprotokolle – die Docker-Container-Protokolle oder die Protokolle Ihres MCP-Clients bei Verwendung der npm-Distribution
3. Kontaktieren Sie unser Support-Team unter helpdesk@deque.com mit:
   • Ihr MCP-Client und dessen Version
   • Ihre Docker-Version (Docker-Distribution) oder Node.js-Version (npm-Distribution)
   • Vollständige Fehlermeldungen
   • Schritte zur Reproduktion des Problems