Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Symptom: In /mcp steht syliusadmin-stage-mcp oder syliusadmin-prod-mcp auf failed, es sind keine Tools verfügbar.
Prüfen:
prod/.env noch keine Zugangsdaten enthält..env der Umgebung SYLIUS_ENVIRONMENT, SYLIUS_BASE_URL, SYLIUS_ADMIN_EMAIL und SYLIUS_ADMIN_PASSWORD gesetzt? Fehlt eine Variable, bricht der Start mit einer Meldung ab, die die Variable und die gelesene Datei nennt.~/.claude-plugin-syliusadmin/<stage oder prod>/.env? Fehlt sie, bricht der Start ab; /syliusadmin:setup legt sie an.SYLIUS_ENVIRONMENT in der Datei zum Ordner (stage im Ordner stage, prod im Ordner prod)? Sonst verweigert der Server den Start.Lösung zu 5: bin/run-server startet den Interpreter aus ~/.claude-mcp-syliusadmin/venv (Windows: %USERPROFILE%\.claude-mcp-syliusadmin\venv), der Setup-Skill legt das venv aber unter ~/.claude-plugin-syliusadmin/venv an. Lege es am erwarteten Pfad an:
python3 -m venv ~/.claude-mcp-syliusadmin/venv
~/.claude-mcp-syliusadmin/venv/bin/pip install -r <plugin-verzeichnis>/requirements.txt
Starte Claude Code danach neu.
Symptom: Tool-Aufrufe scheitern mit "Sylius-Login fehlgeschlagen" und einem HTTP-Status.
Prüfen:
SYLIUS_ADMIN_EMAIL und SYLIUS_ADMIN_PASSWORD? Die Meldung enthält nur den Status, nie die Daten.SYLIUS_API_KEY exakt mit dem Wert überein, den die Stage-Instanz erwartet? Der Header geht auch beim Login mit.SYLIUS_BASE_URL (Zertifikat, Firewall, VPN)?Symptom: Der Login klappt, aber jeder Aufruf endet mit HTTP 403.
Lösung: Dem Admin-User fehlt die Rolle ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS allein reicht nicht. Ergänze die Rolle im Feld roles der Tabelle sylius_admin_user, siehe Konfiguration.
Symptom: Ein Tool scheitert mit "außerhalb des erlaubten Scopes", "kein DELETE" oder "read-only".
Erklärung: Das ist beabsichtigt. Der Server blockiert Bestellungen, Kunden, Promotions und Admin-User sowie jedes Löschen außer bei Marketplace-Links. Channels und Eingabefeld-Definitionen sind nur lesbar. Siehe Sicherheit.
Symptom: add_product_image oder add_taxon_image mit image_path scheitert sofort mit einem Hinweis auf SYLIUS_IMAGE_UPLOAD_BASE_DIR.
Lösung: Setze die Variable in der .env auf einen absoluten, existierenden Pfad und starte neu. Der Bildpfad muss innerhalb dieses Verzeichnisses liegen und auf dem Rechner des MCP-Servers existieren. Liegt das Bild schon auf dem CDN, geht es ohne diese Einstellung per cdn_url.
Symptom: add_product_image mit cdn_url liefert einen Sylius-Fehler.
Prüfen: Ist das Plugin sylius-cdn-product-images im Shop installiert? Ohne Plugin gibt es diesen Weg nicht. Zusammen mit cdn_url sind variant_codes nicht erlaubt.
Symptom: set_product_active oder update_product mit enabled=true wird mit einem Hinweis auf fehlende Varianten abgelehnt.
Lösung: Lege zuerst mit add_variant mindestens eine Variante an. Ohne Variante hätte die Produktseite im Shop keinen Preis und würde mit HTTP 500 abstürzen.
Symptom: Meldung zu fehlenden Channel-Preisen oder Optionswerten.
Lösung:
channel_pricings braucht einen Preis für jeden Channel, dem das Produkt zugeordnet ist (get_product zeigt sie).option_value_codes genau einen Wert je Option des Produkts.Symptom: create_shipping_method oder update_shipping_method scheitert bei der Konfiguration.
Lösung: Bei flat_rate und per_unit_rate braucht configuration einen Eintrag für jeden Channel des Shops (list_channels), nicht nur für die in channel_codes genannten. Aktualisierst du configuration, rules oder channel_codes, ersetzt das den kompletten Bestand.
Symptom: metaTitle, canonicalPathOverride, robotsIndex oder robotsFollow werden akzeptiert, sind aber beim Zurücklesen nicht da.
Erklärung: Die Felder gibt es nur, wo die Übersetzungs-Klassen des Shops die Traits des Plugins sylius-seo-suite-pro nutzen. Sonst ignoriert die API sie ohne Fehlermeldung. Lies die Übersetzung immer zurück.
Symptom: option_codes wird akzeptiert, die Optionsliste des Produkts bleibt aber gleich.
Erklärung: Sylius übernimmt die Änderung nur, solange keine Variante des Produkts Optionswerte hat, und meldet das nicht als Fehler. Entferne zuerst die Varianten (im Sylius-Admin).
Was ist MCP? Das Model Context Protocol ist ein offener Standard, mit dem Claude externe Dienste über Tools ansprechen kann. Dieser Server ist die Brücke zur Sylius Admin API und läuft lokal über stdio.
Kann Claude Bestellungen bearbeiten? Nein. Dafür gibt es weder Tools noch Zugriff durch die Allowlist.
Warum kann ich nichts löschen? Das ist Absicht: Löschen bleibt im Sylius-Admin. Ausnahme sind Marketplace-Links. Versandarten kannst du archivieren.
Kann ich Stage und Prod gleichzeitig nutzen? Ja, das Plugin startet beide Server gleichzeitig. Jeder Server bedient genau eine Umgebung.
Läuft der Server auf Windows? Der Setup-Skill und die Starter-Skripte (bin/run-server.cmd) berücksichtigen Windows, inklusive der Python-Suche per py -3.