Shopware Admin: Fehlerbehebung
Fehlerbehebung für den Shopware Admin MCP-Server: Start schlägt fehl, Authentifizierung, Berechtigungen, Timeouts, veraltete Daten, Content-Profile, Medien-Upload und häufige Fragen.
Shopware Admin: Fehlerbehebung
Diese Dokumentation bezieht sich immer auf den aktuellen Stand des main-Branches.
Fehlermeldungen des Servers findest du in der Antwort des Tools und, für Startfehler, auf stderr des Prozesses.
Der Server startet nicht
Symptom: Der Server erscheint in Claude Code nicht als verbunden, es sind keine Tools da.
Starte ihn zum Test direkt: node ~/.claude/mcp-servers/shopwareadmin/dist/index.js. Er wartet dann auf stdin. Bricht er ab, steht der Grund auf stderr:
| Meldung | Ursache und Lösung |
|---|---|
Missing required environment variable: <NAME> |
Pflichtvariable fehlt. Prüfe .env im Deployment-Verzeichnis (siehe Installation). |
Invalid SHOPWARE_URL: ... |
Keine gültige URL, zum Beispiel ohne https://. |
Invalid WIKIJS_BASE_URL: |
Die Variable fehlt oder ist keine URL. Setze eine beliebige gültige URL, sie wird nicht verwendet. |
CACHE_TTL_... must be positive |
Eine der Cache-Variablen ist 0 oder negativ. Lösche sie oder setze einen positiven Wert. |
Invalid JSON in content-profiles.json ... |
Die Datei ist kein gültiges JSON. |
Invalid content-profiles.json at ... |
Ein Feld verletzt das Schema, die Meldung listet jedes Feld. Siehe Konfiguration. |
Weitere Punkte: Ist dist/ aktuell (npm run build)? Ist Node.js 20 oder neuer installiert? Wird die .env gefunden (Deployment-Verzeichnis zuerst, dann Arbeitsverzeichnis)?
Authentifizierung schlägt fehl
Symptom: Antwort mit AUTH_FAILED.
| Meldung | Bedeutung |
|---|---|
Invalid client credentials |
Shopware antwortet mit 401. Client-ID oder Client-Secret stimmen nicht. |
OAuth2 authentication failed: <Status> |
Anderer Fehlerstatus von /api/oauth/token. Prüfe, ob die Integration aktiv ist und die URL zum Shop gehört. |
OAuth2 token request timed out |
Keine Antwort innerhalb von 15 Sekunden. Prüfe Erreichbarkeit und Netzwerk. |
Berechtigungsfehler
Symptom: API_ERROR mit httpStatus: 403.
Die Integration hat für die angesprochene Entität kein Recht. Die benötigten Entitäten je Bereich stehen unter Konfiguration. Schreibende Tools brauchen Schreibrechte.
Timeouts und Rate Limit
Shopware API request timed out after 30s: Der Shop antwortet zu langsam. Wiederhole den Aufruf später, die Meldung gilt als wiederholbar.RATE_LIMITED: Shopware drosselt. Der Server hat bereits dreimal mit Wartezeit wiederholt, warte einige Sekunden.- Bei
mail_template_send_testbedeutetRATE_LIMITEDdas eigene Limit von 5 pro Template und 10 insgesamt pro Minute. Die Meldung nennt die Wartezeit.
Daten sind veraltet oder fehlen
Symptom: Eine Änderung im Shopware-Admin erscheint im Tool nicht, oder ein Eintrag wird nicht gefunden.
Einzelabfragen und einige Listen werden im Arbeitsspeicher des Servers zwischengespeichert:
| Daten | Cache-Dauer |
|---|---|
Produkt (product_get), Medium, Flow, Cross-Selling (Einzelabruf) |
5 Minuten |
| Kategorien, Hersteller-Liste ohne Suche, Eigenschaften, Textbausteine, Mail-Templates | 10 Minuten |
Bestellung (order_get) |
2 Minuten |
| Produkt-, Medien-, Bestell-, Flow-, Mail-Template- und SEO-URL-Listen, Suchen | kein Cache |
Ein Neustart des Servers leert den Cache. Der Server leert betroffene Einträge selbst, wenn er etwas ändert. category_update leert den gesamten Cache.
Prüfe außerdem: Produkte sind nach product_create inaktiv. category_list blendet inaktive Kategorien ohne includeInactive aus.
Content-Generierung
| Symptom | Ursache und Lösung |
|---|---|
Unknown content style: "<Name>". Available: ... |
style nennt kein vorhandenes Profil. Die Meldung listet die gültigen Namen. |
| Immer derselbe Stil | Der Kategoriename passt nicht exakt (Groß- und Kleinschreibung) zu einem Schlüssel in categoryMapping, es gilt defaultProfile. |
| Neue Profile werden nicht übernommen | Die Datei wird nur beim Start gelesen. Starte den Server neu. Prüfe außerdem, welche Datei gefunden wird: CONTENT_PROFILES_PATH, dann Deployment-Verzeichnis, dann Arbeitsverzeichnis. |
| Keine Textbausteine in der Antwort | Das Profil hat includeSnippets: false oder der Aufruf setzt includeSnippets: false, dann bietet der Server keine Bausteine an. Es sind auch keine aktiven Bausteine angelegt, oder die übergebenen snippetIds passen nicht zu aktiven Bausteinen. |
API-Fehler bei Textbausteinen oder snippet_list |
Das Plugin mit der Entität mmd-product-snippet fehlt im Shop (oder der Integration fehlt das Leserecht). Bei includeSnippets: true scheitert dann schon die Content-Generierung mit einem API-Fehler, sie liefert nicht einfach eine leere Liste. |
wikiUrl ist null |
Erwartet, das Feld ist ohne Funktion. |
Medien-Upload
Symptom: Failed to upload media from URL oder eine Ablehnung der URL.
Internal/private network URLs are not allowed: Die URL zeigt auf eine interne Adresse, siehe Sicherheit.- Shopware muss die URL selbst erreichen können. Die Datei wird nicht vom MCP-Server geladen.
- Nach einem fehlgeschlagenen Download wird das angelegte Medium gelöscht.
Weitere Meldungen
| Meldung oder Code | Bedeutung |
|---|---|
PRODUCT_NUMBER_EXISTS |
Die Artikelnummer ist vergeben. |
INVALID_INPUT mit details |
Ein Parameter verletzt die Eingabeprüfung, field nennt den Parameter. |
Unknown tool: <Name> |
Das Tool gibt es nicht. |
Failed to send test mail |
Shopware konnte nicht senden. Prüfe die Mail-Konfiguration im Shopware-Admin. |
Product/Order/... not found |
Der Datensatz existiert nicht oder die ID ist falsch. |
Error: fetch failed |
Netzwerkfehler zwischen Server und Shop. |
Häufige Fragen
Funktioniert der Server mit Shopware 5? Nein. Er nutzt die Shopware-6-Admin-API.
Kann Claude Bestellungen ändern? Nein. Die Bestell-Tools sind rein lesend.
Kann der Server mehrere Shops bedienen? Eine Instanz liest genau einen Satz Zugangsdaten und einen Standard-Verkaufskanal. Für weitere Shops registrierst du weitere Instanzen mit eigener Konfiguration unter anderem Namen.
Werden Produkte sofort im Shop sichtbar? Nein. Sie entstehen inaktiv und werden erst mit product_set_active aktiviert.
Wo ist der Nachfolger? Siehe die Statusangabe auf der Übersichtsseite.