Zum Hauptinhalt springen

Shopware-Anbindung

Der Shopware-Connector verbindet Assistenten im CLYE AI direkt mit dem nativen MCP-Server einer Shopware-Instanz. Damit kann ein Assistent Produkte, Bestellungen, Kunden und weitere Shopware-Entitäten suchen, lesen, anlegen und aktualisieren – ohne eigenen MCP-Prozess auf eurer Seite und ohne npm- oder stdio-basierte Brücke.

Die Verbindung läuft als Streaming HTTP gegen den Shopware-Endpunkt /api/_mcp. CLYE AI nutzt dabei die Integration-Credentials eurer Shopware-Instanz.

Voraussetzungen​

AnforderungDetails
Shopware-VersionMindestens 6.7.11.0. Instanzen darunter unterstützen MCP nicht nativ und sind nicht anbindbar.
Feature-FlagMCP_SERVER=1 in der Shopware-.env-Datei (experimentelles Feature)
IntegrationAccess Key und Secret Access Key aus einer Shopware-Integration
ErreichbarkeitDie Shopware-Instanz muss vom CLYE AI aus per HTTP oder HTTPS erreichbar sein
important

Der Shopware MCP-Server ist ein experimentelles Feature hinter dem Feature-Flag MCP_SERVER. APIs, Tool-Namen und Verhalten können sich bis zur stabilen Version noch ändern.

Shopware vorbereiten​

Bevor du den Connector im CLYE AI einrichtest, muss die Shopware-Instanz MCP aktivieren und Zugangsdaten bereitstellen.

Schritt 1: MCP-Server aktivieren​

Füge in der .env-Datei eurer Shopware-Installation folgende Zeile hinzu:

MCP_SERVER=1

Speichere die Datei und starte Shopware bzw. leere den Cache neu, damit der Endpunkt /api/_mcp verfügbar wird. Ist das Feature-Flag nicht gesetzt, hat der MCP-Server keinen Laufzeit-Overhead – und ist für externe Clients nicht erreichbar.

Weitere Konfigurationsmöglichkeiten (z. B. Tool-Allowlists) findest du in der offiziellen Shopware-MCP-Dokumentation.

Schritt 2: Integration anlegen​

Erstelle auf der Shopware-Instanz eine Integration für den MCP-Client. Auf dem Server:

bin/console integration:create "MCP Client"

Der Befehl gibt einen Access Key (beginnt mit SWIA…) und einen Secret Access Key aus. Notiere beide Werte sicher – der Secret Key wird danach nicht erneut angezeigt.

Für Produktivumgebungen empfiehlt Shopware, den --admin-Schalter wegzulassen und stattdessen gezielte ACL-Berechtigungen für die Integration zu vergeben. Jeder MCP-Aufruf wird gegen die Shopware-Berechtigungen der Integration geprüft.

Verbindungsdaten im Überblick​

Für die Anbindung im CLYE AI brauchst du drei Werte:

FeldBeschreibungBeispiel
Shop-URLHost und optional Port ohne http:// oder https://shop.example.com oder localhost:8081
Access KeyIntegration Access Key aus Shopware (beginnt mit SWIA)SWIA…
Secret KeyIntegration Secret Access Key(geheim)

Aus Shop-URL und Protokoll ergibt sich die MCP-Adresse:

http://{hostPort}/api/_mcp

oder

https://{hostPort}/api/_mcp

CLYE AI wählt im Katalog automatisch HTTP oder HTTPS passend zu eurer Eingabe. Bei manueller Einrichtung trägst du die vollständige URL selbst ein.

Im CLYE AI verbinden​

Variante A: Aus dem Katalog (empfohlen)​

  1. Öffne Einstellungen und wechsle zum Bereich MCP-Server.
  2. Klicke auf Neuer MCP-Server bzw. Aus dem Katalog installieren.
  3. Wähle Shopware.
  4. Trage ein:
    • Shop-URL (Domain ohne Protokoll, z. B. shop.example.com)
    • Access Key
    • Secret Key
  5. Bestätige die Installation.

Der Katalog registriert den Server als shopware-connector und verbindet sich per Streaming HTTP direkt mit /api/_mcp auf eurer Shopware-Instanz.

Variante B: Manuell hinzufügen​

  1. Öffne Einstellungen → MCP-Server.
  2. Klicke auf Manuell hinzufügen.
  3. Trage folgende Werte ein:
    • Server-ID: shopware-connector
    • Typ: Streaming HTTP
    • URL: https://shop.example.com/api/_mcp (oder http://localhost:8081/api/_mcp für lokale Entwicklung)
    • Headers (JSON):
{
  "sw-access-key": "SWIA...",
  "sw-secret-access-key": "..."
}
  1. Klicke auf Speichern.

Der Server erscheint danach in der Liste der installierten MCP-Server und steht in Assistenten zur Verfügung, die diesen MCP-Server nutzen dürfen.

Authentifizierung​

Shopware authentifiziert MCP-Anfragen über die Integration-Header:

  • sw-access-key – öffentlicher Access Key der Integration
  • sw-secret-access-key – geheimer Secret Key

Es gibt keinen separaten OAuth-Ablauf im CLYE AI. Die Berechtigungen richten sich nach der Shopware-Integration und den zugehörigen ACL-Regeln. Der Assistent sieht und darf nur die Aktionen ausführen, die der Integration erlaubt sind.

Verfügbare MCP-Werkzeuge​

Welche Daten und Aktionen verfügbar sind, hängt von der Shopware-Version, der Integration und den vergebenen Berechtigungen ab. Zusätzlich kann Shopware über Allowlists einschränken, welche Tools überhaupt exponiert werden.

WerkzeugFunktion
shopware-entity-searchProdukte, Bestellungen, Kunden und weitere Entitäten suchen
shopware-entity-readEinzelne Entität lesen
shopware-entity-schemaDatenmodell abrufen
shopware-entity-upsertEntitäten anlegen oder aktualisieren
shopware-entity-deleteEntitäten löschen
shopware-entity-aggregateAggregationen durchführen
shopware-media-uploadMedien hochladen
shopware-order-stateBestell-Status ändern
shopware-system-config-readSystem-Konfiguration lesen
shopware-system-config-writeSystem-Konfiguration schreiben
shopware-theme-configTheme-Konfiguration lesen und anpassen

Schreibende Werkzeuge unterstützen in Shopware typischerweise einen Dry-Run, mit dem der Assistent Änderungen vorab prüfen kann, bevor sie ausgeführt werden.

Typische Einsatzfälle​

  • Katalog-Recherche: „Welche Produkte haben wir in Kategorie X?" – der Assistent sucht direkt in Shopware.
  • Bestellungen prüfen: Offene Bestellungen auflisten, Details lesen oder Status aktualisieren.
  • Kundeninformationen: Kundendaten und zugehörige Bestellungen abrufen.
  • Produktpflege: Produktbeschreibungen, Preise oder Bestände per Assistent anpassen.
  • Reporting: Aggregationen über Umsatz, Bestellungen oder Katalogdaten auswerten.
  • Theme und Konfiguration: System- oder Theme-Einstellungen lesen und bei Bedarf anpassen.

Sicherheit und Betrieb​

  • Version prüfen: Nur Shopware 6.7.11.0 und höher unterstützen den nativen MCP-Server.
  • Feature-Flag: Ohne MCP_SERVER=1 in der .env ist keine Anbindung möglich.
  • Minimale Rechte: Vergebe der Integration nur die ACL-Berechtigungen, die der Assistent wirklich braucht.
  • Secret schützen: Den Secret Access Key wie ein API-Passwort behandeln und nicht in Chats oder Tickets teilen.
  • Erreichbarkeit: Stelle sicher, dass der CLYE AI die Shopware-URL erreichen kann (Firewall, TLS-Zertifikat, interne DNS).
  • Experimentell: Plane mit möglichen API-Änderungen bis zur stabilen Shopware-Version.

Kurz gesagt​

Der Shopware-Connector verbindet den CLYE AI direkt mit dem nativen MCP-Server eurer Shopware-Instanz ab Version 6.7.11.0. Voraussetzung sind das Feature-Flag MCP_SERVER=1, eine Shopware-Integration mit Access Key und Secret Key sowie die Shop-URL ohne Protokoll. Über elf Werkzeuge können Assistenten Entitäten suchen, lesen, schreiben und Shopware-spezifische Aktionen wie Bestellstatus-Änderungen oder Medien-Uploads ausführen.

Verwandte Seiten​

Inhalt