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.
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)?
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. |
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.
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.mail_template_send_test bedeutet RATE_LIMITED das eigene Limit von 5 pro Template und 10 insgesamt pro Minute. Die Meldung nennt die Wartezeit.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.
| 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. |
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.| 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. |
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.