Dies ist die kompakte deutsche Fassung. Die vollständige Dokumentation, die Parameterreferenz und alle Aufnahmen sind auf Englisch: README.md.
---
## Worum es geht
Ein Shopware-6-Shop sind rund zweihundert Entitäten hinter einer Admin-API.
Wer einen Assistenten fragt „Ist im Shop alles in Ordnung?", braucht für eine
ehrliche Antwort sieben Suchen mit Criteria-Filtern, drei State Machines mit
ihren technischen Namen, ein paar Aggregationen und ein OAuth-Token, das der
Assistent niemals wiederholen darf. Hängt man ein Modell direkt an diese API,
bekommt es all das, samt dem Recht, einen Preis per `PATCH` zu ändern, weil ein
Prompt es so wollte.
Das Model Context Protocol hat „gib dem Modell echte Werkzeuge" zu einer
Zeile Konfiguration gemacht. Es sagt nichts darüber, wie ein gutes Werkzeug
für einen *Shop* aussieht: welche der zweihundert Entitäten an einem
Dienstagmorgen zählen, was „hängende Bestellung" heißt, oder dass eine
Bestandskorrektur erst gezeigt und dann gesendet gehört.
**shopware-mcp ist diese Schicht.** Ein kleiner Server, der zum Host MCP
spricht und zum Shop die Admin-API, und Shopware gut genug kennt, um mit
einem Aufruf zu beantworten, was früher einen Nachmittag im Admin gekostet hat:
| | |
|---|---|
| **Kuratierte Werkzeuge** | Produkte, Bestellungen samt Verlauf, Belege, Kunden, Kategorien, Aktionen, Bewertungen, Zahlungs- und Versandarten, Plugins, Bestand, Verkaufskanäle, geplante Aufgaben, die Shop-Einstellungen: zwanzig Werkzeuge mit kompaktem JSON, exakten Trefferzahlen, Beschreibungen für ein Modell und Shopwares eigenen Criteria-Filtern. Keine erfundene Abfragesprache. |
| **Ein Audit** | `shop_audit` prüft sechzehn Dinge in einem Aufruf: bezahlte Bestellungen, die nie versandt wurden oder keine Rechnung haben, unbezahlte Bestellungen, die alt werden, versandte Bestellungen, die nie abgeschlossen wurden, Produkte ohne Bestand, die beim aktuellen Absatz ausgehen, ohne Bild, ohne Lieferzeit oder in keinem Verkaufskanal sichtbar, abgelaufene Aktionen, Kanäle im Wartungsmodus, Storefronts ohne Impressum, AGB, Datenschutz, Widerruf oder Versandhinweise, Bewertungen, die auf Freigabe warten, geplante Aufgaben, die nicht mehr laufen, Erweiterungen mit Update, und welche EU-Pflichten durch eine installierte Erweiterung abgedeckt scheinen. Priorisiert, mit Beispielen und einem Hinweis je Befund. Dasselbe Audit läuft als `shopware-mcp audit` aus Cron oder CI, ganz ohne MCP-Host. |
| **Reports und eine Prognose** | `sales_report` lässt Shopware rechnen: brutto, netto, Durchschnittsbestellung, Umsatz je Währung und Kanal, Bestellungen je Status, eine Zeitreihe nach Tag, Woche oder Monat, die Top-Produkte und auf Wunsch die Veränderung zum Vorzeitraum. `customer_report` macht dasselbe für Menschen: neue Konten, Gastanteil, Wiederkäuferanteil, Top-Kunden nach Umsatz. `stock_forecast` macht aus Absatzgeschwindigkeit und Bestand Reichweite in Tagen, Ausverkaufsdatum und Nachbestellmenge. Die Zahlen wurden gegen SQL auf derselben Datenbank geprüft. |
| **Eine Hintertür** | `entity_schema` beschreibt jede der über 200 Entitäten, auch die eigenen Entitäten von Plugins, und `entity_search` fragt sie mit denselben Filtern ab und lässt Shopware über die Treffermenge aggregieren: Bestellungen je Zahlungsart, Umsatz je Monat, alles, was terms, sum oder histogram hergeben. Entitäten mit Zugangsdaten werden verweigert, Geheimnisse im Rest entfernt. |
| **Eine Bremse** | Nur lesend, solange der Server nicht mit `--allow-write` gestartet wird. Und selbst dann ist jeder Schreibzugriff zuerst ein Probelauf, der den genauen Request zeigt, und ein Schreib-Budget kann die echten Schreibzugriffe je Prozess begrenzen. Versenden, als bezahlt markieren, erinnern, erstatten, Bestand korrigieren, Notiz, Beleg erzeugen, Produkt oder Aktion anlegen, Produktbild setzen, Bewertung freigeben, Kunde ändern, fünfzig Rechnungen auf einmal, ein Tag setzen: fünfzehn schmale Schreibzugriffe, sonst nichts. Geheimnisse tauchen nie in Ausgaben, Logs oder Fehlern auf. |
Shops sind nicht gleich, also ist es die Werkzeugliste auch nicht: Beim Start
schaut der Server nach, welche Erweiterungen installiert sind, und registriert
zusätzliche Werkzeuge für die, die er kennt. Ein schlichter Shop bekommt den
Kern. Ein Shop mit mehr Plugins bekommt einen größeren Agenten, ohne
Konfiguration.
---
## So sieht es aus
Jede Aufnahme ist echte Ausgabe des Servers gegen einen Shopware-6.7.13-Testshop
mit generierten Demodaten, abgespielt aus den Transkripten in
[`docs/demo/`](docs/demo). Die Aufnahmen sind auf Englisch; Werkzeugaufrufe und
Ergebnisse sind wörtlich, zum Lesen gekürzt.
**Eine Frage, dreizehn Prüfungen.** Drei bezahlte Bestellungen warten auf den
Versand, die Storefront ist im Wartungsmodus, eine Sommeraktion hat den August
überlebt. Die Antwort nennt Bestellnummern und Beträge und bietet den sicheren
nächsten Schritt an.
**Zahlen, die der Shop selbst gerechnet hat.** Summen, Kanäle, Status, eine
Monatsreihe und das Top-Produkt für acht Monate, aus einem Aufruf.
**Kein Werkzeug dafür? Dafür gibt es ein Schema.** Für Hersteller gibt es kein
eigenes Werkzeug. Der Agent liest das Schema der Entität, findet `mediaId` und
filtert darauf. Derselbe Weg führt zu jeder anderen Entität, eigene inklusive.
**Schreibzugriffe zeigen erst ihre Karten.** Mit `--allow-write` kommt eine
Bestandskorrektur als der Request zurück, den sie senden *würde*. Erst ein
ausdrückliches `dryRun: false` verändert den Shop, und das Ergebnis wird aus
Shopware neu gelesen.
**Versenden, dann belegen.** Eine Lieferungs-Transition sind zwei Requests, die
vor dem Senden gezeigt werden: die Sendungsnummer auf die Lieferung, dann der
Statuswechsel. Der Verlauf der Bestellung nennt danach Transition, Status und
wer sie ausgelöst hat.
**Ein Produkt und sein Startcode, aus einem Satz.** `product_create` nimmt den
Standardsteuersatz des Shops, leitet den Nettopreis ab und sagt das im
Probelauf. Die Aktion kommt inaktiv an, damit niemand einen Code sieht, bevor
er geprüft wurde.
**Moderation mit Antwort.** Zwei Bewertungen warten auf Freigabe. Der Spam
bleibt verborgen, die Beschwerde wird zusammen mit der öffentlichen Antwort des
Shops freigegeben, und niemand musste in den Admin.
**Menschen, nicht nur Umsatz.** Neue Konten je Gruppe, wie viele Kunden
bestellt haben und wie viele wiederkamen, der Gastanteil und die Top-Kunden mit
ihrem Anteil am Zeitraum, neben dem Zeitraum davor.
**Ein Shop mit mehr Plugins bekommt einen größeren Agenten.** Die Kernwerkzeuge
sind sofort da. Die Erweiterungssuche endet im Hintergrund, vier Werkzeuge
kommen dazu, der Host wird zum Aktualisieren aufgefordert, und eine
Compliance-Frage hat eine Antwort.
**Nachbestellen, bevor es weh tut.** `stock_forecast` liest sechs Monate
Bestellpositionen über eine Aggregation, verbindet sie mit dem aktuellen
Bestand und sagt je Produkt, wie viele Tage bleiben, wann der Bestand auf null
fällt und wie viel zu bestellen ist. Neun davon sind schon überverkauft, zwei
sind heute noch in Ordnung und im Oktober nicht mehr.
**Dasselbe Audit, ganz ohne Host.** `shopware-mcp audit` gibt die Befunde als
Markdown aus und endet mit Exit-Code 1, wenn etwas kritisch ist (oder mit
`--fail-on warning` schon bei einer Warnung). In Cron gehängt, kommt die Mail;
in CI gehängt, bricht der Job ab. `shopware-mcp report` macht dasselbe für die
Zahlen.
**Ein Shop mit Betriebs-Plugin bekommt einen Betriebs-Agenten.** FroshTools ist
die quelloffene Werkzeugkiste, die viele Shopware-Hoster installieren. Ist sie
da, kommen drei Werkzeuge dazu: die Gesundheitsprüfungen der Plattform, die
Message-Queue samt Worker und die Sicherheitshinweise zu Abhängigkeiten. Der
Agent unterscheidet veraltete Suchergebnisse von einem toten Worker.
**Sechsundfünfzig Rechnungen, drei auf einmal.** `order_documents_bulk_create`
findet die bezahlten Bestellungen ohne Rechnung, älteste zuerst, und zeigt den
einen Request, der sie erzeugen würde, bevor er läuft. Jede Bestellung zählt
gegen das Schreib-Budget. Dann erklärt `scheduled_tasks_list`, wie der Rückstau
entstand: 31 von 33 Aufgaben überfällig, keine je gelaufen, der Scheduler steht.
`tag_assign` markiert die Bestellung für das Team und legt das Tag dabei an.
**Vorher wissen, was geht.** `shopware-mcp doctor` prüft, was die Integration lesen darf, liest ihre Rolle für die Schreibrechte, wo das erlaubt ist, und nennt je Werkzeug das fehlende Recht. Ein Administrator bekommt lauter Haken, eine Support-Rolle erfährt genau, was zu vergeben ist.
---
## In 60 Sekunden
**1.** Im Shopware-Admin eine Integration anlegen: *Einstellungen → System → Integrationen → Integration hinzufügen*. Zugangsschlüssel-ID und Geheimschlüssel kopieren; der Geheimschlüssel wird nur einmal angezeigt. Für einen Entwicklungsshop *Administrator* ankreuzen, in Produktion eine Leserolle vergeben ([welche Rechte](docs/self-hosting.md#shopware-permissions)).
**2.** Den Assistenten die Zugangsdaten prüfen und die Host-Konfiguration schreiben lassen:
```bash
npx shopware-mcp init # fragt URL, Schlüssel und Geheimnis ab, testet sie, zeigt die Konfiguration
npx shopware-mcp init --for claude-desktop --write # oder trägt sie direkt in die Datei des Hosts ein
npx shopware-mcp doctor # welche Werkzeuge diese Integration nutzen kann, und was fehlt
```
Oder den Server von Hand starten:
```bash
export SHOPWARE_URL=https://shop.example.com
export SHOPWARE_CLIENT_ID=SWIA...
export SHOPWARE_CLIENT_SECRET=...
npx shopware-mcp # stdio (Standard)
npx shopware-mcp --http --port 3333 # Streamable HTTP auf http://127.0.0.1:3333/mcp
npx shopware-mcp --allow-write # zusätzlich die abgesicherten Schreibwerkzeuge
```
**3.** Host verbinden (oder `init --write` machen lassen):
Claude Desktop
`shopware-mcp.mcpb` aus dem [aktuellen Release](https://github.com/bnymnDev/shopware-mcp/releases/latest) laden und doppelklicken, oder in `claude_desktop_config.json` eintragen:
```json
{
"mcpServers": {
"shopware": {
"command": "npx",
"args": ["-y", "shopware-mcp"],
"env": {
"SHOPWARE_URL": "https://shop.example.com",
"SHOPWARE_CLIENT_ID": "SWIA...",
"SHOPWARE_CLIENT_SECRET": "..."
}
}
}
}
```
Claude Code
```bash
claude mcp add shopware \
-e SHOPWARE_URL=https://shop.example.com \
-e SHOPWARE_CLIENT_ID=SWIA... \
-e SHOPWARE_CLIENT_SECRET=... \
-- npx -y shopware-mcp
```
Cursor, VS Code, Zed, Windsurf und andere stdio-Hosts
Alle nehmen dieselben drei Felder. Cursor liest `.cursor/mcp.json`, VS Code `.vscode/mcp.json` (unter `servers` statt `mcpServers`), Zed seinen `context_servers`-Block. Der Eintrag entspricht dem von Claude Desktop oben. Hosts, die die [offizielle MCP-Registry](https://registry.modelcontextprotocol.io) lesen, finden den Server als `io.github.bnymnDev/shopware-mcp`.
Docker und HTTP-Hosts
```bash
docker run --rm -p 3333:3333 \
-e SHOPWARE_URL=https://shop.example.com \
-e SHOPWARE_CLIENT_ID=SWIA... -e SHOPWARE_CLIENT_SECRET=... \
ghcr.io/bnymndev/shopware-mcp
```
Das Image liefert Streamable HTTP unter `http://127.0.0.1:3333/mcp`. Mit `-e SHOPWARE_MCP_HTTP_TOKEN=` verlangt der Endpunkt `Authorization: Bearer `; ohne Token auf localhost lassen oder hinter einen Proxy stellen, der authentifiziert ([Hinweise zum Betrieb](docs/self-hosting.md)).
**4.** Fragen. Die erste nützliche Frage ist meist *„Ist im Shop alles in Ordnung?"*
---
## Fragen, die es beantwortet
| Sie sagen | Der Agent ruft auf |
|---|---|
| „Ist im Shop alles in Ordnung?" | `shop_audit` |
| „Wie lief der August?" | `sales_report { from, to, interval: "week" }` |
| „Welche Produkte haben weniger als 5 auf Lager?" | `products_search` mit einem `range`-Filter, oder der Prompt `low_stock_report` |
| „Fasse Bestellung 10042 für eine Support-Antwort zusammen." | `orders_get`, oder der Prompt `order_summary` |
| „Welche Kunden haben mehr als zehnmal bestellt?" | `customers_search` mit einem `range`-Filter auf `orderCount` |
| „Ist das PayPal-Plugin aktuell?" | `plugins_list` |
| „Welche Hersteller haben kein Logo?" | `entity_schema`, dann `entity_search` auf `product_manufacturer` |
| „Setze den Bestand von SW10084 auf 40." | `stock_set`, erst als Probelauf, dann echt |
| „Bestellung 10042 ist mit DHL raus, Sendungsnummer 00340434." | `order_delivery_transition { transition: "ship", trackingCodes }` |
| „Die Überweisung zu 10038 ist da." | `order_transaction_transition { transition: "paid" }` |
| „Wie war die letzte Woche im Vergleich zur Vorwoche?" | `sales_report { compareWithPrevious: true }`, oder der Prompt `weekly_review` |
| „Schick mir die Rechnung zu 10042." | `order_documents_list`, dann liefert `document_download` die PDF |
| „Notiz zu 10042: Kunde hat angerufen, Versand Montag." | `order_note` |
| „Was ist mit Bestellung 10042 passiert, und wer war das?" | `order_history` |
| „Wer ist Kunde 10042 und was hat er zuletzt bestellt?" | `customers_get` und `orders_search`, oder der Prompt `customer_profile` |
| „Wer waren unsere besten Kunden im Quartal?" | `customer_report { from, to, topCustomers: 20 }` |
| „Welche Bewertungen warten auf Freigabe?" | `reviews_search` mit `status: false`, oder der Prompt `review_moderation` |
| „Gib die Bewertung von Dominique frei und bedank dich." | `review_moderate { approved: true, comment }` |
| „Welche Zahlungsarten bietet die Storefront an?" | `payment_methods_list`, `shipping_methods_list` |
| „Lege einen 10-%-Code AUTUMN10 für Oktober an." | `promotion_create`, inaktiv, bis Sie es anders sagen |
| „Lege das Produkt Bank, SW10200, 119 Euro, 3 auf Lager an." | `product_create`, Nettopreis aus dem Steuersatz abgeleitet |
| „Zwei kamen vom Kunden zurück, buche sie auf SW10084." | `stock_set { delta: 2 }` |
| „Was muss ich in den nächsten zwei Wochen nachbestellen?" | `stock_forecast`, oder der Prompt `reorder_list` |
| „Bestellungen je Zahlungsart im letzten Monat, mit Umsatz?" | `entity_search` auf `order` mit einer `terms`-Aggregation und einer `sum` darin |
| „Welche bezahlten Bestellungen haben noch keine Rechnung? Erzeuge sie." | `shop_audit`, dann `order_documents_bulk_create { type: "invoice" }`, zuerst als Probelauf |
| „Laufen die Cronjobs überhaupt?" | `scheduled_tasks_list { onlyProblems: true }` |
| „Markiere diesen Kunden als VIP." | `tag_assign { entity: "customer", add: ["VIP"] }` |
| „Ist der Gastkauf an, und was ist der Standardsteuersatz?" | `shop_settings` |
| „Gib SW10084 dieses Bild: https://…/bank.jpg" | `product_cover_set`, der Shop lädt es selbst |
| „Thumbnails fehlen, ist die Plattform in Ordnung?" | `frosh_health` und `frosh_queue`, wenn FroshTools installiert ist |
| „Welche Werkzeuge scheitern mit dieser Integration?" | kein Werkzeug: `npx shopware-mcp doctor` |
| „Schick mir jeden Montag das Audit." | auch kein Werkzeug: `shopware-mcp audit --fail-on warning` per Cron |
Filter sind Shopware-Criteria-Filter (`equals`, `contains`, `range`, `equalsAny`) auf Shopware-Feldpfaden, Assoziationen wie `manufacturer.name` eingeschlossen. Was sich in der Admin-API filtern lässt, lässt sich auch hier filtern. Der [Spickzettel](docs/quickstart.md#filters-cheat-sheet) zeigt die üblichen Fälle.
---
## Werkzeuge
| Werkzeug | Zugriff | Zweck |
|---|---|---|
| [`shop_info`](docs/tools.md#shop_info) | read | Shop info |
| [`shop_settings`](docs/tools.md#shop_settings) | read | Shop settings |
| [`sales_channels_list`](docs/tools.md#sales_channels_list) | read | List sales channels |
| [`products_search`](docs/tools.md#products_search) | read | Search products |
| [`products_get`](docs/tools.md#products_get) | read | Get product |
| [`orders_search`](docs/tools.md#orders_search) | read | Search orders |
| [`orders_get`](docs/tools.md#orders_get) | read | Get order |
| [`order_history`](docs/tools.md#order_history) | read | Order history |
| [`order_documents_list`](docs/tools.md#order_documents_list) | read | List order documents |
| [`document_download`](docs/tools.md#document_download) | read | Download document PDF |
| [`customers_search`](docs/tools.md#customers_search) | read | Search customers |
| [`customers_get`](docs/tools.md#customers_get) | read | Get customer |
| [`categories_list`](docs/tools.md#categories_list) | read | List categories |
| [`promotions_list`](docs/tools.md#promotions_list) | read | List promotions |
| [`reviews_search`](docs/tools.md#reviews_search) | read | Search product reviews |
| [`payment_methods_list`](docs/tools.md#payment_methods_list) | read | List payment methods |
| [`shipping_methods_list`](docs/tools.md#shipping_methods_list) | read | List shipping methods |
| [`plugins_list`](docs/tools.md#plugins_list) | read | List plugins and apps |
| [`scheduled_tasks_list`](docs/tools.md#scheduled_tasks_list) | read | Scheduled tasks |
| [`stock_get`](docs/tools.md#stock_get) | read | Get stock |
| [`stock_forecast`](docs/tools.md#stock_forecast) | read | Stock forecast |
| [`sales_report`](docs/tools.md#sales_report) | read | Sales report |
| [`customer_report`](docs/tools.md#customer_report) | read | Customer report |
| [`shop_audit`](docs/tools.md#shop_audit) | read | Shop health audit |
| [`entity_schema`](docs/tools.md#entity_schema) | read | Entity schema |
| [`entity_search`](docs/tools.md#entity_search) | read | Search any entity |
| [`stock_set`](docs/tools.md#stock_set) | write (guarded) | Set stock (guarded) |
| [`product_update`](docs/tools.md#product_update) | write (guarded) | Update product (guarded) |
| [`product_create`](docs/tools.md#product_create) | write (guarded) | Create product (guarded) |
| [`product_cover_set`](docs/tools.md#product_cover_set) | write (guarded) | Set product cover image (guarded) |
| [`order_state_transition`](docs/tools.md#order_state_transition) | write (guarded) | Transition order state (guarded) |
| [`order_delivery_transition`](docs/tools.md#order_delivery_transition) | write (guarded) | Transition delivery state (guarded) |
| [`order_transaction_transition`](docs/tools.md#order_transaction_transition) | write (guarded) | Transition payment state (guarded) |
| [`order_note`](docs/tools.md#order_note) | write (guarded) | Add internal order note (guarded) |
| [`order_document_create`](docs/tools.md#order_document_create) | write (guarded) | Create order document (guarded) |
| [`order_documents_bulk_create`](docs/tools.md#order_documents_bulk_create) | write (guarded) | Create documents for many orders (guarded) |
| [`promotion_toggle`](docs/tools.md#promotion_toggle) | write (guarded) | Toggle promotion (guarded) |
| [`promotion_create`](docs/tools.md#promotion_create) | write (guarded) | Create promotion (guarded) |
| [`customer_update`](docs/tools.md#customer_update) | write (guarded) | Update customer (guarded) |
| [`review_moderate`](docs/tools.md#review_moderate) | write (guarded) | Moderate review (guarded) |
| [`tag_assign`](docs/tools.md#tag_assign) | write (guarded) | Assign tags (guarded) |
Jeder Parameter jedes Werkzeugs: [docs/tools.md](docs/tools.md). Suchen liefern
`{ total, page, limit, items }` mit exakten Trefferzahlen, `limit` ist auf 50
begrenzt, und Fehler kommen als `{ error: { status, code, detail } }` zurück.
Ressourcen: `shopware://shop`, `shopware://sales-channels`, `shopware://order/{orderNumber}`,
`shopware://product/{productNumber}`, `shopware://customer/{customerNumber}`. Prompts:
`order_summary`, `customer_profile`, `low_stock_report`, `reorder_list`, `review_moderation`,
`weekly_review`.
**Plugin-Werkzeuge.** Beim Start fragt der Server im Hintergrund, welche
Erweiterungen installiert und aktiv sind, und registriert zusätzliche Werkzeuge
für die, die er kennt. Zwei Pakete gibt es heute:
[FroshTools](https://github.com/FriendsOfShopware/FroshTools), das quelloffene
Betriebs-Plugin, mit `frosh_health` (Plattform- und Performance-Prüfungen),
`frosh_queue` (Message-Queue, wartende Nachrichten, Worker) und
`frosh_composer_audit` (Sicherheitshinweise zu Abhängigkeiten), alle nur lesend;
und [Merqo](https://github.com/bnymnDev/merqo) mit `merqo_health`,
`merqo_einvoice_inbox`, `merqo_returns_search` und `merqo_abandoned_carts`.
Shops ohne das Plugin sehen dessen Werkzeuge nie, und die Kernwerkzeuge verhalten
sich in beiden Fällen gleich. `--no-extensions` schaltet den Mechanismus ab.
Unterstützung für die Erweiterungen eines anderen Anbieters ist eine Datei
unter `src/extensions/`; Pull Requests sind willkommen.
---
## Sicherheit
- **Standardmäßig nur lesend.** Ohne `--allow-write` (oder `SHOPWARE_MCP_ALLOW_WRITE=true`) werden die Schreibwerkzeuge gar nicht registriert. Was ein Agent nicht sieht, kann er nicht aufrufen.
- **Jeder Schreibzugriff ist zuerst ein Probelauf.** Alle fünfzehn Schreibwerkzeuge, von `stock_set` bis `tag_assign`, stehen auf `dryRun: true` und liefern `{ dryRun: true, wouldSend: { method, url, body } }`, als Liste, wenn ein Aufruf mehrere Requests braucht. Ein echter Schreibzugriff liefert die neu gelesene Entität.
- **Ein Schreib-Budget.** `SHOPWARE_MCP_MAX_WRITES=20` weist den einundzwanzigsten echten Schreibzugriff eines Prozesses mit `WRITE_BUDGET_EXHAUSTED` ab; Probeläufe bleiben frei. Kein Prompt kann das aufheben.
- **Schmale Schreibzugriffe.** `product_update` ändert Name, Beschreibung, Aktiv-Status und den Preis einer Währung; `product_create` legt ein einfaches Produkt an, mehr nicht; `product_cover_set` fügt ein Bild hinzu (JPEG, PNG, WebP, GIF oder AVIF, nie SVG), das der Shop selbst lädt. `promotion_create` erzeugt einen Warenkorbrabatt, inaktiv, solange nichts anderes gesagt wird. `customer_update` ändert Aktiv-Status und Kundengruppe. Die Transition-Werkzeuge bewegen nur Status, nie Geld. Belege erzeugt Shopwares eigener Generator, versendet werden sie von diesem Server nie; `order_documents_bulk_create` macht höchstens fünfzig je Aufruf und belastet das Schreib-Budget je Bestellung. `tag_assign` setzt oder entfernt Tags nach Namen und lässt den Rest des Datensatzes in Ruhe. Nichts löscht. Sonst nichts.
- **Bereinigte Lesezugriffe.** `entity_search` entfernt Passwörter, Schlüssel, Tokens und Hashes aus jeder Antwort und verweigert Entitäten, die Zugangsdaten oder Systeminterna enthalten: Benutzer, Integrationen, ACL-Rollen, Apps, Systemkonfiguration.
- **Nirgends Geheimnisse.** Zugangsdaten erscheinen nie in Ausgaben, Logs oder Fehlermeldungen. Logs gehen nur nach stderr.
- **Keine Telemetrie.** Der Server spricht mit Ihrem Shop und mit Ihrem Host. Mit niemandem sonst.
- **HTTP-Transport.** Mit `SHOPWARE_MCP_HTTP_TOKEN` verlangt `/mcp` diesen Bearer-Token, verglichen in konstanter Zeit. Ohne Token auf localhost lassen (Standard) oder hinter einen authentifizierenden Reverse Proxy stellen; der Server warnt, wenn er ohne Token weiter erreichbar ist.
- **Requests laufen ab.** Ein Shop, der nicht mehr antwortet, kostet einen Request 30 Sekunden (`SHOPWARE_MCP_TIMEOUT_MS`), nicht die ganze Sitzung.
Etwas gefunden? Siehe [SECURITY.md](SECURITY.md).
---
## Konfiguration
| Variable | Pflicht | Hinweise |
|---|---|---|
| `SHOPWARE_URL` | ja | Basis-URL des Shops, z. B. `https://shop.example.com` |
| `SHOPWARE_CLIENT_ID` | ja | Zugangsschlüssel-ID der Integration |
| `SHOPWARE_CLIENT_SECRET` | ja | Geheimschlüssel der Integration |
| `SHOPWARE_MCP_ALLOW_WRITE` | nein | `true` registriert die Schreibwerkzeuge. Standard: aus |
| `SHOPWARE_MCP_MAX_WRITES` | nein | Echte Schreibzugriffe, die ein Prozess insgesamt ausführen darf; `0` (Standard) heißt keine Grenze |
| `SHOPWARE_MCP_DEFAULT_LIMIT` | nein | Standard-Seitengröße für Suchen (Standard 20, maximal 50) |
| `SHOPWARE_MCP_EXTENSIONS` | nein | `false` schaltet Plugin-Werkzeuge und die Erweiterungssuche beim Start ab |
| `SHOPWARE_LANGUAGE_ID` | nein | Sprach-UUID für übersetzte Felder (`sw-language-id`). Standard: Shopsprache |
| `SHOPWARE_MCP_TIMEOUT_MS` | nein | Timeout je Admin-API-Request in Millisekunden (Standard 30000, 1000 bis 600000) |
| `SHOPWARE_MCP_HTTP_TOKEN` | nein | Bearer-Token, den der HTTP-Transport auf `/mcp` verlangt (mindestens 16 Zeichen). Standard: keiner |
| `SHOPWARE_MCP_LOG_LEVEL` | nein | `error` (Standard), `warn`, `info`, `debug`. Logs gehen nur nach stderr |
CLI-Flags überschreiben die Umgebung: `--allow-write`, `--max-writes `, `--no-extensions`, `--http`, `--port `, `--host `, `--log-level `. Befehle: `doctor [--json]` und `init [--for ] [--write]`.
---
## Open Core
Alles in diesem Repository ist MIT und bleibt es. Es deckt einen Shop, einen Betreiber und interaktive Nutzung ab.
Vom selben Autor stammt [Merqo](https://github.com/bnymnDev/merqo), eine kommerzielle Suite von
Shopware-Erweiterungen für EU-Compliance und den täglichen Betrieb. Dieser Server erkennt sie und
ergänzt passende Werkzeuge, setzt sie aber nie voraus.
Agenturen und Händler, die das im großen Stil betreiben, brauchen meist mehr, und genau das baue und betreibe ich für Kunden:
- **Multi-Shop**: ein MCP-Endpunkt, der auf Dutzende Shops mit eigenen Zugangsdaten und Rechten routet
- **Gehostet mit Audit-Trail**: jeder Werkzeugaufruf protokolliert mit Wer, Was und Wann, rollenbasierter Zugriff, SLA
- **Massenoperationen und Migrationen**: Preis- und Bestandsupdates in Masse, Katalogimporte, sichere Rollbacks
- **Eigene Agenten und Shopware-Plugins**: Workflows für Ihr ERP, PIM oder Ihren Support-Desk
Interesse? Ein Issue mit dem Label `consulting` oder eine Nachricht über [github.com/bnymnDev](https://github.com/bnymnDev). Sie setzen shopware-mcp produktiv ein und wollen, dass es gepflegt bleibt? [Sponsoring](https://github.com/sponsors/bnymnDev) hilft.
---
## Dokumentation
Alle weiteren Dokumente sind auf Englisch:
| Dokument | Inhalt |
|---|---|
| [docs/quickstart.md](docs/quickstart.md) | Integration, erster Start, Host-Konfigurationen, Beispielfragen, Filter-Spickzettel |
| [docs/tools.md](docs/tools.md) | Jedes Werkzeug mit jedem Parameter, aus dem Code generiert |
| [docs/self-hosting.md](docs/self-hosting.md) | Transporte, Docker, Reverse Proxies, Shopware-Rechte, Betrieb |
| [docs/decisions.md](docs/decisions.md) | Designentscheidungen und ihre Begründung |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Einrichtung, Grundregeln, End-to-End-Tests, Releases |
| [SECURITY.md](SECURITY.md) | Was melden und wohin |
| [CHANGELOG.md](CHANGELOG.md) | Was sich in jeder Version geändert hat |
## Lizenz
[MIT](LICENSE)
Wenn shopware-mcp eine Frage beantwortet hat, die der Admin nicht konnte, hilft ein Stern dem nächsten Shop, es zu finden.
