Shopware 6 MCP: Deinen Shop mit Claude und Codex verbinden

ACHTUNG: Das Feature wird bei Shopware als experimentell in der Dokumentation deklariert.

Welche Produkte sind gerade ausverkauft, obwohl sie in den letzten Wochen haeufig bestellt wurden? Eine wichtige Frage die du dir als Shopbetreiber stellst oder stellen solltest.

Die passenden Daten zusammenzutragen, dauert aber etwas: Produkte filtern, Bestellungen auswerten und Ergebnisse miteinander vergleichen.

Mit dem MCP-Server von Shopware kannst du diese Aufgabe von einem KI-Agenten bearbeiten lassen. Er bekommt Zugriff auf freigegebene Funktionen deines Shops, kann Daten abfragen und die Ergebnisse fuer dich aufbereiten.

In diesem Beitrag erfaehrst du, wie MCP funktioniert, wie du Claude Desktop oder Codex (auf macOS und Windows) mit Shopware verbindest und mit welchen Aufgaben du sinnvoll einsteigst.

Was ist MCP und was bringt es fuer Shopware? 

MCP steht fuer Model Context Protocol. Das ist ein Standard der beschreibt, wie KI-Anwendungen auf Informationen und Funktionen anderer Systeme zugreifen koennen.

Shopware stellt dafuer einen MCP-Server in deinem Shop bereit. Deine KI-Anwendung verbindet sich als Client mit diesem Server und erfaehrt, welche Faehigkeiten zur Verfuegung stehen. Du beschreibst dein Anliegen in natuerlicher Sprache, der Agent waehlt passende Funktionen aus und verarbeitet deren Ergebnisse.

Wie der Shopware Copilot nur auf deinem Rechner, statt in der Shop Administration.

Dieser Beitrag behandelt den administrativen Zugang ueber `/api/_mcp`. Es gibt fuer die Storefront auch den Zugang ueber `/store-api/_mcp` fuer deine Endkunden KI Agenten. Beide Zugaenge haben unterschiedliche Aufgaben und Berechtigungskonzepte. 

Der praktische Vorteil liegt vor allem bei wechselnden Fragen: Du kannst eine Auswertung eingrenzen, Rueckfragen stellen und das Ausgabeformat aendern. Wie viel Arbeit das spart, haengt davon ab, ob die verfuegbaren Daten und Funktionen zu deiner Aufgabe passen.

Ich konzentriere mich in diesem Beitrag auf `/api/_mcp`, d.h. die Anbindung an die Administration.

Tools, Resources und Prompts: die drei  Bausteine

Ein MCP-Server kann drei Arten von Faehigkeiten anbieten:

• Tools: Funktionen mit definierten Eingaben ausfuehren, z.B. Produkte mit shopware-entity-search suchen
• Resources: Informationen als Kontext bereitstellen, z.B. Verkaufskanaele ueber shopware://sales-channels abrufen
• Prompts: Wiederverwendbare Anleitungen fuer die KI, z.B. Shopware-Wissen mit shopware-context laden

Ein Tool kann Daten lesen oder veraendern. Eine Produktsuche ist also genauso ein Tool, wie das Aktualisieren eines Artikels. Resources  stellen Informationen zum Lesen bereit. Diese muessen nicht dauerhaft unveraenderlich sein. Prompts helfen dabei, eine Aufgabe mit den verfuegbaren Informationen und Funktionen zu bearbeiten.

Typischerweise waehlt das Modell passende Tools aus, die Anwendung stellt Resources als Kontext bereit und der Nutzer waehlt eine Prompt-Vorlage. Die konkrete Bedienung haengt vom Client ab.

Welchen fertigen Prompt liefert Shopware mit?

In der Core-Referenz ist `shopware-context` dokumentiert. Dieser Prompt erklaert unter anderem die Beziehungen zwischen Produkten, Bestellungen und Kunden, das Suchformat von Shopware und typische Ablaeufe mit mehreren Tools. Ausserdem erhaelt er Hinweise zum Umgang mit Fehlern und Aenderungen Previews.

Ein unterstuetzender Client kann diesen Prompt abrufen und in den Kontext der Unterhaltung uebernehmen. Allein die Verbindung zum Server garantiert nicht, dass der Client ihn automatisch laedt. Die spaeteren Beispielauftraege in diesem Beitrag sind selbst formulierte Chatnachrichten, d.h. du kannst sie ohne eigene MCP-Prompt-Vorlage verwenden.

Welche Shopware-Version brauchst du?

Den eingebauten MCP Server kannst du bereits ab 6.7.11.0 nutzen, musst es aber freischalten. Vor 6.7.11.0 ist keine Nutzen moeglich. Ab 6.7.14.0 ist es ohne extra Freischaltung direkt nutzbar.

Shopware fuer die Verbindung vorbereiten

Fuer die Einrichtung brauchst du Zugriff auf die Shopware-Administration und fuer die Konsolenbefehle Zugriff auf den Server z.B. ueber SSH. Wenn du eine Agentur hast, hilft sie dir dabei. Teste alles vorher auf einer Staging Umgebung, damit du sicher mit dem Umgang bist. Eine falsche Konfiguration kann zu Probleme fuehren.

1. MCP-Verfuegbarkeit pruefen

Wenn dein Shop zwischen 6.7.11.0 und 6.7.13.x liegt, musst du `MCP_SERVER=1` setzen, z.B. in der .env (oder .env.local) Datei. 

Ab 6.7.14.0 funktioniert es normalerweise. Wenn du dir sicher sein willst, kannst du pruefen ob das mcp-bundle von symfony installiert ist mit: `composer show symfony/mcp-bundle` -> wenn es fehlt, musst du es installieren. Ich habe das Ganze mit 6.7.14.2 getestet.

2. Eine eigene Integration mit begrenzten Rechten anlegen

Zuerst wollen wir eine Rollen anlegen: Dazu unter Einstellungen > Benutzer & Berechtigungen > Rollen eine passende Rolle anlegen. Fuer die Produktsuche brauchst du Produkt-Leserechte. Bestellauswertungen benoetigen zusaetzliche Leserechte auf die verwendeten Bestelldaten und gegebenenfalls verbundene Datensaetze.

Was solltest du da einstellen an Rechten? Im Prinzip musst du dich fragen was du alles machen moechtest mit dem KI Agenten. Wenn du Produktpflege machen willst, brauchst du Lesen, Erstellen und Bearbeiten bei Produkten, Kategorien, Herstellern und Eigenschaften.

Erstelle fuer die KI-Anbindung eine eigene Integration. Das geht ueber die Administration: 

Einstellungen > Integrationen > Integration anlegen

Denk daran die Rollen die du zuvor erstellt hast auszuwaehlen bei der Integration.

Du erhaelst eine Zugangs-ID und einen Sicherheitsschluessel. Beide sicher speichern, weil wir die spaeter fuer die lokale Konfiguration  brauchen. Am besten nutzt du einen  Passwort Manager.

Achte darauf, dass du KEINE Administrator Rechte vergibst. Es scheint bequem zu sein, ist aber ein riesiges Problem, weil du der KI damit alle Rechte gibst. 

Begrenze auch die MCP Faehigkeiten. Das geht ueber MCP-Allowlist bearbeiten:

Fuer den Einstieg reichen die benoetigten Lese- und Discovery Tools.

Rolle und Allowlist erfuellen dabei verschiedene Aufgaben: Die Rolle bestimmt die Zugriffsrechts, die Allowlist begrenzt die bereitgestellten MCP-Faehigkeiten. Beides muss aufeinander abgestimmt sein. Die benoetigten Rechte in der Rolle werden bei dem entsprechenden Tool angezeigt: 

3. Den Server-Katalog pruefen

Mit dem Befehl siehst du die registrierten Faehigkeiten des Admin-MCP-Servers:

`bin/console debug:mcp`

Die Ausgabe enthaelt unter anderem Tools, Prompts und Resources. Damit pruefst du die serverseitige Registrierung. Ob dein Desktop-Client den Shop erreicht und sich anmelden kann, testest du anschliessend mit einer echten Abfrage.

CLI oder Desktop App

Ich habe verschiedene Wege getestet, dabei empfand ich die Anbindung und Nutzung ueber die CLI am einfachsten. Die Einrichtung hat auf Anhieb geklappt, weil ich nur jeweils einen Befehl ausfuehren musste und keine Konfigurationsdateien anpassen musste.

Die Desktop Apps nutzen auch die selben MCP Konfigurationen, allerdings hatte ich mit den Desktop Apps oefter Probleme.

Claude Code

Du kannst es Projektbezogen hinzufuegen oder global. In meinem Beispiel moechte ich es global machen, daher der Zusatz --scope user. Wenn du es nicht global hinzufuegst, musst du fuer den MCP claude in deinem Projektordner starten.

In einem Terminal deiner Wahl den Befehl eingeben:

claude mcp add --scope user --transport http shopware https://mcp.dev.mc.m8.emzcustomers.de/api/_mcp \
--header "sw-access-key: xxx" \
--header "sw-secret-access-key: xxx"

https://mcp.dev.mc.m8.emzcustomers.de ist die Url von deinem Shop und der MCP Endpoint wird erreicht durch https://mcp.dev.mc.m8.emzcustomers.de/api/_mcp

sw-access-key ist dabei die Zugangs-ID und sw-secret-access-key der Sicherheitsschluessel von deiner angelegten Integration.

Die Einrichtung unter Windows funktioniert genauso. Ich musste aber die erste Abfrage zweimal ausfuehren, weil die Tools beim ersten Aufruf nicht richtig geladen werden konnten.

Codex

Laut Shopware Dokumentation funktioniert es mit codex `mcp add --url` nicht, weil die Art der Authentifizierung nicht klappt. Daher schreiben wir es in die config.toml file. Auch hier wieder global. Dazu rufen wir die .codex/config.toml in deinem Home Verzeichnis. Du erreichst die Datei auch aus der Desktop App wenn du unten in die Einstellungen (oder Mac + ,) > Konfiguration und rechts auf config.toml klickst. 

Da kannst du ganz unten das einfuegen:

[mcp_servers.shopware]
url = "https://mcp.dev.mc.m8.emzcustomers.de/api/_mcp"
http_headers = { "sw-access-key" = "xxx", "sw-secret-access-key" = "xxx" }
enabled = true

sw-access-key ist dabei die Zugangs-ID und sw-secret-access-key der Sicherheitsschluessel von deiner Integration.

Die Einrichtung unter Windows funktioniert genauso.

Problem: Mit der neuesten Version funktioniert es mit Codex aktuell NICHT. Der Fix oder ein Workaround kommt voraussichtlich in 6.7.15.0. Gleicher Fehler unter macOS und Windows.

Die erste Verbindung mit einer Leseabfrage testen

Starte mit einer kleinen, leicht ueberpruefbaren Aufgabe: 

Suche ueber den verbundenen Shopware-MCP nach fuenf Produkten. Gib Artikelnummer, Name und den aktuellen Lagerbestand aus. Verwende nur diese Felder und aendere keine Daten. Falls die Abfrage scheitert, beschreibe den Fehler, statt Produktdaten zu erfinden.

Pruefe anschliessend die verwendeten Tool Aufrufe und vergleiche die Ergebnisse stichprobenartig mit der Administration. Eine plausibel formulierte Antwort allein belegt noch keine funktionierende Verbindung.

Ab 6.7.14.2 werden Werkzeuge schrittweise entdeckt. Ein frischer Client sieht zunaechste unter anderem `shopware-tool-search`, `shopware-toolsets-list` und `shopware-toolset-enable`. Wenige sichtbare Tools bedeuten deshalb nicht automatisch, dass die Einrichtung fehlgeschlagen ist.

Wenn alles passt, koennte deine Ausgabe so aussehen:

Jetzt koennen wir loslegen

Die Verbindung steht und Claude code ist ready unseren Shop ueber MCP zu bedienen. Es gibt so viel was wir machen koennten.

Hier sind ein paar Ideen:

• Pruefe meine Produkte auf fehlende Bilder, duerftige Beschreibungen und fehlende SEO-Texte. Zeige die zehn wichtigsten Baustellen.
• Welche Produkte verkaufen sich in den letzten 30 Tagen am besten und koennten bei gleichbleibendem Absatz bald ausverkauft sein?
• Nimm fuenf Produkte mit kurzen Beschreibungen und erstelle bessere Texte, Meta-Titel und englische Uebersetzungen. Zeige vorher und nachher.
• Stelle aus verfuegbaren Produkten drei Geschenkideen unter 100 Euro zusammen - mit passenden Werbetexten und einer Begruendung fuer die Auswahl.
• Finde bezahlte Bestellungen, die seit mehr als drei Tagen noch nicht versendet wurden, und sortiere sie nach Wartezeit.
• Welche Produkte werden haeufig zusammen gekauft? Schlage daraus passende Zubehoer-Empfehlungen fuer zehn Artikel vor.

Fuer die Geschaeftsfuehrer koennte auch das interessant sein:

• Fasse die letzte Woche zusammen: Umsatz, Bestellungen, Warenkorg, Stornos und groesste Veraenderungen. Welche drei Themen brauchen meine Aufmerksamkeit?
• Zerlege unseren Umsatzrueckgang nach Verkaufskanal, Kategorie, sowie Neu- und Bestandskunden. Woher kommt rechnerisch der groesste Rueckgang?
• Welche Produkte haben viel Bestand und wenig Absatz? Priorisiere nach gebundenem Einkaufswet und schlage moegliche Massnahmen vor.
• Welche umsatzstarken Produkte bringen nach Rabatten, Warenkosten, Retouren und Versand wenig Deckungsbeitrag?
• Vergleiche Kundengruppen nach Erstkaufmonat: Wieviele kaufen innerhalb von 90 Tagen erneut, und welchen Umsatz erziehen sie pro Kunde?
• Wieviel Umsatz entfaellt auf unsere zehn groessten Kunden, fuenf wichtigsten Marken und zwanzig staerksten Produkte?
• Welche Geschaeftskunden bestellen haeufig kleine Mengen und erhalten gleichzeitig hohe Rabatte oder kostenlosen Versand? Berechne ihren Deckungsbeitrag.
• Vergleiche drei Szenarien: 5% hoeherer Warenkorb, 10% mehr Bestellungen oder zwei Prozentpunkte weniger Rabatt. Wie veraendern sich Umsatz und Deckungsbeitrag unter der jeweiligen Annahme?

Wichtig ist natuerlich, dass die Ergebnisse validiert werden muessen. Wie auch beim Entwickeln koennen wir KI generierten Code nicht blind vertrauen. Ebenso auch den Ergebnissen von den Prompts oben.

Fazit

Bisher klingt es vielversprechend und ich bin sehr gespannt in welche Richtung sich das entwickeln wird. Gerade mit KI und Voice oder auch automatisierte KI Agenten kann das ein spannendes und nuetzliches Thema werden.

Alles was du ueber die Administration erledigen kannst auch der KI Agent mit den passenden Rechten fuer die erledigen kann. Seien es Analysen machen, Gutscheine anlegen, Produkte mit fehlerhaften Daten finden, SEO Daten optimieren, Datenpflegen an sich, usw.

Aber auch komplexere Einstellungen wie neue Sprachen einfuehren hat ganz gut funktioniert. Wenn du dir unsicher bist, kannst du auch nachfragen und dir jeden Schritt freigeben lassen und diesen pruefen.

Hast du schonmal den MCP ausprobiert? Welche Tools nutzt du dafuer? Und welche Aufgaben gibst du dem KI Agenten?

Interessante Links

• Shopware Dokumentation MCP: https://developer.shopware.com/docs/products/tools/mcp-server/getting-started.html
• Durch eigene Plugins erweitern: https://developer.shopware.com/docs/guides/plugins/plugins/mcp-server.html