¶ Inhaltsverzeichnis
- Ueberblick
- Features
- Anwendungsfaelle
- Anforderungen
- Installation
- Konfiguration
- Content-Profile konfigurieren
- Verfuegbare Tools
- Verwendung
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz
- Support und Changelog
¶ Ueberblick
claude-mcp-shopwareadmin ist ein MCP Server (Model Context Protocol), der Claude die direkte Steuerung der Shopware 6 Admin API ermoeglicht. Mit 43 spezialisierten Tools deckt er den kompletten Shop-Management-Workflow ab: von der Produkterstellung ueber Content-Generierung und SEO-Optimierung bis hin zu Bestelluebersichten und BFSG-konformem Media-Management.
Dieser MCP Server ermoeglicht Claude die direkte Interaktion mit deinem Shopware 6 Shop - Produkte anlegen, Beschreibungen generieren, SEO optimieren, Bestellungen pruefen und Media verwalten, ohne manuelles Copy-Paste oder Browser-Wechsel.
¶ Kern-Philosophie
- User legt Struktur an (Produkte, Varianten, Bilder im Shopware Admin)
- Claude uebernimmt Content (Texte, SEO, Verwaltungsaufgaben)
- Safety First - Produkte werden IMMER inaktiv angelegt
- Type-Safe - TypeScript + Zod-Validierung ueberall
¶ Features
- 43 MCP Tools fuer umfassende Shop-Verwaltung
- Produktverwaltung: Erstellen, Lesen, Aktualisieren, Suchen, Aktivieren/Deaktivieren
- Automatische Content-Generierung mit Stil-Erkennung (Kreativ vs. Software)
- Konfigurierbare Content-Profile ueber externe JSON-Datei (eigene Stile, Tonalitaet, Anrede, Zielgruppe) - Neu in v1.1.0
- SEO-Metadaten-Generierung (Meta Title, Description, Keywords)
- Kategoriebaum-Navigation mit Breadcrumbs
- E-Mail-Template-Verwaltung mit Twig-Variablen-Referenz
- Media-Management mit BFSG-Compliance-Audit (Alt-Text-Pruefung)
- Bestelluebersichten und Statistiken (Read-only)
- Cross-Selling-Verwaltung mit AI-Empfehlungen
- SEO-URL-Audit und -Regenerierung
- Flow Builder Steuerung
- OAuth2 Client Credentials mit automatischem Token-Refresh
- Retry-Logik mit Exponential Backoff (Rate Limiting, Token Refresh)
- InMemory-Cache mit konfigurierbaren TTLs
- MCP Protocol 1.0 kompatibel (stdio Transport)
¶ Anwendungsfaelle
Produktpflege: "Lege ein neues Produkt an mit dem Namen 'Stickmuster Blumenwiese', Preis 4,99 EUR in der Kategorie Stickdateien" - Claude erstellt das Produkt direkt im Shop (inaktiv zum Pruefen).
Content-Generierung: "Schreibe eine Produktbeschreibung fuer Produkt XY" - Claude erkennt automatisch den Stil (Kreativ fuer Stickdateien, Professionell fuer Software) und generiert passenden Content.
Eigene Content-Stile: Du kannst eigene Stil-Profile definieren (z.B. "B2B" mit formeller Anrede) und Kategorien zuordnen - ohne Code-Aenderungen. Siehe Content-Profile konfigurieren.
SEO-Optimierung: "Optimiere die SEO-Daten fuer alle Produkte in der Kategorie Software" - Claude generiert Meta-Titel, Beschreibung und Keywords pro Produkt.
BFSG-Compliance: "Pruefe welche Produktbilder keinen Alt-Text haben" - Claude fuehrt ein BFSG-Audit durch und listet alle betroffenen Medien.
Bestellanalyse: "Zeig mir die Bestellstatistiken der letzten 30 Tage" - Claude ruft aggregierte Daten ab (Umsatz, Bestellanzahl, Durchschnittswert).
¶ Anforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| Node.js | >= 20.0.0 | LTS empfohlen |
| npm | >= 9 | Wird mit Node.js mitgeliefert |
| Claude Desktop oder CLI | Aktuell | MCP-Client erforderlich |
| Shopware 6 | >= 6.5 | Admin API muss erreichbar sein |
| Shopware Integration | - | API-Zugangsdaten mit passenden Berechtigungen |
Die Shopware-Integration muss Lese-/Schreibrechte auf die relevanten Entitaeten haben (Produkte, Kategorien, Mail-Templates, Media, etc.). Fuer reine Leseoperationen genuegen Read-Rechte.
git clone https://github.com/markus-michalski/claude-mcp-shopwareadmin.git
cd claude-mcp-shopwareadmin
npm install
npm run build
# Nach dem Build in das MCP-Server-Verzeichnis kopieren
mkdir -p ~/.claude/mcp-servers/shopwareadmin
cp -r dist node_modules package.json .env ~/.claude/mcp-servers/shopwareadmin/
# Optional: Content-Profile anpassen und mitkopieren
cp content-profiles.example.json ~/.claude/mcp-servers/shopwareadmin/content-profiles.json
¶ Konfiguration
¶ Environment Variables
Erstelle eine .env-Datei basierend auf .env.example:
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
SHOPWARE_URL |
Ja | - | Basis-URL des Shopware-Shops (z.B. https://shop.example.com) |
SHOPWARE_CLIENT_ID |
Ja | - | OAuth2 Client ID der Shopware-Integration |
SHOPWARE_CLIENT_SECRET |
Ja | - | OAuth2 Client Secret der Shopware-Integration |
SHOPWARE_DEFAULT_TAX_ID |
Ja | - | Standard-Steuersatz-ID (32-Zeichen Hex) |
SHOPWARE_DEFAULT_TAX_RATE |
Ja | 19 |
Standard-Steuersatz in Prozent |
SHOPWARE_DEFAULT_SALES_CHANNEL_ID |
Ja | - | Standard-Sales-Channel-ID (32-Zeichen Hex) |
SHOPWARE_DEFAULT_CURRENCY_ID |
Nein | b7d2554b0ce847cd82f3ac9bd1c0dfca |
Waehrungs-ID (Standard: EUR) |
CONTENT_PROFILES_PATH |
Nein | - | Pfad zur content-profiles.json (absolut oder relativ zum cwd). Siehe Content-Profile konfigurieren |
WIKIJS_BASE_URL |
Nein | https://faq.markus-michalski.net |
Basis-URL fuer Wiki.js-Verlinkungen |
CACHE_TTL_CATEGORIES |
Nein | 3600000 |
Cache-TTL fuer Kategorien (ms, 1 Stunde) |
CACHE_TTL_PROPERTIES |
Nein | 3600000 |
Cache-TTL fuer Properties (ms, 1 Stunde) |
CACHE_TTL_SNIPPETS |
Nein | 300000 |
Cache-TTL fuer Snippets (ms, 5 Minuten) |
LOG_LEVEL |
Nein | info |
Log-Level: debug, info, warn, error |
¶ Shopware-Integration einrichten
- Shopware Admin oeffnen > Einstellungen > System > Integrationen
- Neue Integration erstellen
- Namen vergeben (z.B. "Claude MCP Server")
- Folgende Mindest-Berechtigungen vergeben:
| Entitaet | Lesen | Schreiben | Hinweis |
|----------|-------|-----------|---------||
| product | Ja | Ja | Produkte erstellen/aktualisieren |
| category | Ja | Nein | Kategoriebaum lesen |
| property_group | Ja | Nein | Produkteigenschaften lesen |
| product_manufacturer | Ja | Nein | Hersteller lesen |
| tax | Ja | Nein | Steuersaetze lesen |
| currency | Ja | Nein | Waehrungen lesen |
| mail_template | Ja | Ja | Templates lesen/aktualisieren |
| media | Ja | Ja | Media verwalten, Alt-Texte |
| order | Ja | Nein | Bestellungen lesen |
| sales_channel | Ja | Nein | Sales Channel Kontext |
| seo_url | Ja | Ja | SEO URLs verwalten |
| product_cross_selling | Ja | Ja | Cross-Selling verwalten |
| flow | Ja | Ja | Flow Builder steuern |
- Client ID und Client Secret in die
.env-Datei uebernehmen
Verwende separate Integrationen fuer verschiedene Umgebungen (Staging/Produktion). Teile niemals Client Secrets ueber unsichere Kanaele.
claude mcp add --scope user --transport stdio shopwareadmin -- \
node ~/.claude/mcp-servers/shopwareadmin/dist/index.js
{
"mcpServers": {
"shopwareadmin": {
"command": "node",
"args": ["/home/user/.claude/mcp-servers/shopwareadmin/dist/index.js"],
"env": {
"SHOPWARE_URL": "https://shop.example.com",
"SHOPWARE_CLIENT_ID": "SWIA...",
"SHOPWARE_CLIENT_SECRET": "...",
"SHOPWARE_DEFAULT_TAX_ID": "...",
"SHOPWARE_DEFAULT_SALES_CHANNEL_ID": "..."
}
}
}
}
cd claude-mcp-shopwareadmin
npm run dev
# Server startet mit tsx watch und restartet bei Aenderungen
¶ Content-Profile konfigurieren
Neu in v1.1.0: Content-Stil-Profile sind jetzt ueber eine externe JSON-Datei konfigurierbar. Du kannst eigene Stile, Tonalitaeten, Anrede-Formen und Kategorie-Zuordnungen definieren - ganz ohne Code-Aenderungen.
¶ Konzept
Der MCP Server nutzt Content-Profile, um Produktbeschreibungen und SEO-Texte im passenden Stil zu generieren. Jedes Profil definiert Tonalitaet, Anrede, Textstruktur und Zielgruppe. Ueber ein Kategorie-Mapping wird automatisch das richtige Profil anhand der Produkt-Kategorie ausgewaehlt.
Bisher waren diese Profile fest im Code verankert. Ab v1.1.0 koennen sie ueber eine content-profiles.json frei angepasst werden.
¶ Suchpfad-Prioritaet
Der Server sucht die Konfigurationsdatei in dieser Reihenfolge:
CONTENT_PROFILES_PATHEnvironment Variable (absolut oder relativ)~/.claude/mcp-servers/shopwareadmin/content-profiles.json(Deployment-Pfad)./content-profiles.json(lokales Verzeichnis)
Wird keine Datei gefunden, werden die eingebauten Standard-Profile (Creative + Software) verwendet.
Die Konfigurationsdatei wird beim Server-Start einmalig geladen und mit Zod vollstaendig validiert. Fehlerhafte Dateien fuehren zu einem klaren Fehler mit Verweis auf
content-profiles.example.json.
¶ Datei-Struktur
Erstelle eine content-profiles.json basierend auf der mitgelieferten content-profiles.example.json:
{
"language": "de",
"defaultProfile": "creative",
"profiles": {
"creative": {
"tonality": "Persoenlich, warm, emotional",
"addressing": "du",
"structure": [
"Emotionaler Einstieg (Frage/Anekdote)",
"Was ist es?",
"Technische Details (Format, Groesse)",
"Anwendungstipps"
],
"targetAudience": "Hobbybastler, Kreative, DIY-Enthusiasten",
"exampleIntro": "Was waere denn Ostern ohne den Osterhasen?",
"includeSnippets": false
},
"software": {
"tonality": "Professionell, sachlich, loesungsorientiert",
"addressing": "Sie",
"structure": [
"Problem-Statement",
"Loesungsansatz",
"Feature-Tabelle",
"Systemanforderungen",
"Dokumentations-Links"
],
"targetAudience": "Shop-Betreiber, Entwickler, Agenturen",
"exampleIntro": "Spam-Schutz ohne Google, ohne Cookies, ohne Bild-Puzzles.",
"includeSnippets": true
}
},
"categoryMapping": {
"Software": "software",
"Stickdateien": "creative",
"Genaehtes": "creative",
"3D-Druck": "creative"
}
}
¶ Profil-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
language |
string | Sprache der generierten Inhalte (z.B. "de", "en") |
defaultProfile |
string | Fallback-Profil, wenn keine Kategorie-Zuordnung passt |
profiles |
object | Stil-Profile (mindestens eins erforderlich) |
profiles.*.tonality |
string | Tonalitaet der Texte (z.B. "Persoenlich, warm") |
profiles.*.addressing |
"du" / "Sie" |
Anrede-Form |
profiles.*.structure |
string[] | Textstruktur-Vorgaben fuer die Generierung |
profiles.*.targetAudience |
string | Zielgruppe fuer den generierten Content |
profiles.*.exampleIntro |
string | Beispiel-Einstieg als Orientierung fuer Claude |
profiles.*.includeSnippets |
boolean | Ob Produkt-Textbausteine eingebunden werden sollen. Erfordert das Plugin Produkt-Textbausteine |
categoryMapping |
object | Zuordnung Kategoriename → Profilname |
Alle Werte in
categoryMappingmuessen auf existierende Profile verweisen. DerdefaultProfilemuss ebenfalls existieren. Zod prueft das beim Laden automatisch.
¶ Beispiel: Eigenes Profil hinzufuegen
Du kannst beliebig viele Profile erstellen. Hier ein Beispiel fuer ein drittes B2B-Profil:
{
"language": "de",
"defaultProfile": "creative",
"profiles": {
"creative": { "..." : "..." },
"software": { "..." : "..." },
"b2b": {
"tonality": "Formell, sachlich, datengetrieben",
"addressing": "Sie",
"structure": [
"Geschaeftlicher Nutzen",
"ROI-Argumentation",
"Technische Spezifikationen",
"Integrations-Moeglichkeiten"
],
"targetAudience": "Einkaufsleiter, IT-Entscheider",
"exampleIntro": "Optimieren Sie Ihre Beschaffungsprozesse.",
"includeSnippets": true
}
},
"categoryMapping": {
"Software": "software",
"Stickdateien": "creative",
"B2B-Loesungen": "b2b"
}
}
Danach den MCP Server neu starten - die neuen Profile sind sofort verfuegbar. Der style-Parameter in product_generate_content und category_generate_content akzeptiert dann auch "b2b".
¶ Verfuegbare Tools
¶ Uebersicht
| Bereich | Tools | Beschreibung |
|---|---|---|
| Produkte | 6 | CRUD, Suche, Aktivierung |
| Content | 4 | Beschreibungen, SEO, Varianten |
| Kategorien | 3 | Baum, Details, SEO-Update |
| Mail-Templates | 4 | CRUD, Test-Versand |
| Bestellungen | 3 | Liste, Details, Statistiken |
| Media | 6 | CRUD, Suche, BFSG-Audit, Upload |
| Flow Builder | 3 | Liste, Details, Toggle |
| Cross-Selling | 5 | CRUD, AI-Empfehlungen |
| SEO URLs | 4 | Liste, Audit, Update, Regenerierung |
| Helfer | 3 | Properties, Hersteller, Snippets |
| Gesamt | 41 |
¶ Produkt-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
product_create |
Neues Produkt erstellen (immer inaktiv!) | name, productNumber, price, categoryId |
product_get |
Produktdetails mit Varianten, Media, Properties | id oder productNumber |
product_list |
Produkte filtern und paginieren | search, categoryId, active, limit, offset |
product_update |
Produkt aktualisieren | id, name, price, description, stock, tags, customFields |
product_set_active |
Produkt aktivieren/deaktivieren | id, active |
search_products |
Volltextsuche ueber alle Produkte | query, limit |
Produkte werden bei der Erstellung IMMER als inaktiv angelegt. Das ist ein bewusstes Sicherheitsfeature - erst pruefen, dann aktivieren.
¶ Content-Generierung
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
product_generate_content |
Generierungs-Prompt fuer Produktbeschreibung | productId, style, maxLength |
product_generate_seo |
SEO-Metadaten generieren | productId, maxTitleLength, maxDescriptionLength |
variant_generate_content |
Variantenspezifische Beschreibung | variantId, inheritFromParent, focusOnOptions |
content_update |
Generierten Content am Produkt speichern | productId, description, metaTitle, metaDescription, keywords |
¶ Automatische Stil-Erkennung
Der Content-Generator erkennt automatisch den passenden Stil anhand der Produktkategorie. Die Zuordnung wird aus der content-profiles.json geladen (oder nutzt die Built-in Defaults):
Standard-Konfiguration:
| Kategorie | Stil | Tonalitaet | Anrede |
|---|---|---|---|
| Stickdateien | creative | Persoenlich, warm, emotional | "du" |
| Genaehtes | creative | Persoenlich, warm, emotional | "du" |
| 3D-Druck | creative | Persoenlich, warm, emotional | "du" |
| Software | software | Professionell, sachlich | "Sie" |
Der Stil kann mit dem Parameter style auch manuell erzwungen werden. Eigene Profile koennen ueber die content-profiles.json hinzugefuegt werden (siehe Content-Profile konfigurieren).
¶ Kategorie-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
category_list |
Kategoriebaum abrufen | depth, parentId, includeInactive |
category_get |
Kategorie-Details + optional Produkte | id, includeProducts, productLimit |
category_generate_content |
SEO-Text fuer Kategorie generieren | id, maxLength, style |
category_update |
Kategorie-SEO aktualisieren | id, description, metaTitle, metaDescription, keywords |
¶ Mail-Template-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
mail_template_list |
Templates durchsuchen | search, limit, offset |
mail_template_get |
Template-Details + Twig-Variablen | id oder technicalName |
mail_template_update |
Template aktualisieren (Twig-Support) | id, subject, contentHtml, contentPlain |
mail_template_send_test |
Test-E-Mail senden | mailTemplateId, recipient |
Der Test-Versand ist rate-limited: maximal 5 Mails pro Template und 10 Mails insgesamt pro Minute.
¶ Bestell-Tools (Read-only)
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
order_list |
Bestellungen filtern | orderStatus, paymentStatus, deliveryStatus, dateFrom, dateTo |
order_get |
Bestelldetails mit Line Items | id oder orderNumber |
order_stats |
Aggregierte Statistiken | dateFrom, dateTo |
¶ Media-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
media_list |
Media filtern (auch nach fehlendem Alt-Text) | hasAlt, mimeTypePrefix, limit |
media_get |
Media-Details + verwendete Produkte | id |
media_update |
Alt-Text und Titel aktualisieren | id, alt, title |
media_search |
Volltextsuche in Media | query, limit |
media_audit_alt |
BFSG-Audit: Produkte ohne Alt-Text | onlyActive, limit |
media_upload_url |
Media von URL hochladen | url, alt, title |
Das BFSG-Audit-Tool (
media_audit_alt) ist essenziell fuer die Einhaltung des deutschen Barrierefreiheitsstaerkungsgesetzes. Alle Produktbilder MUESSEN einen beschreibenden Alt-Text haben.
¶ Flow Builder Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
flow_list |
Flows auflisten und filtern | active, eventName, hasMailAction, search |
flow_get |
Flow-Details mit Sequences | id oder name |
flow_toggle |
Flow aktivieren/deaktivieren | id, active |
¶ Cross-Selling-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
cross_selling_list |
Cross-Selling-Gruppen eines Produkts | productId |
cross_selling_get |
Gruppendetails + zugewiesene Produkte | id |
cross_selling_create |
Neue Cross-Selling-Gruppe erstellen | productId, name, type, assignedProductIds |
cross_selling_update |
Gruppe aktualisieren | id, name, assignedProductIds, active |
cross_selling_suggest |
AI-Kontext fuer Empfehlungen | productId, limit |
¶ SEO-URL-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
seo_url_list |
SEO URLs filtern | routeName, salesChannelId, isCanonical, search |
seo_url_audit |
Audit auf Probleme | routeName, salesChannelId, limit |
seo_url_update |
URL-Pfad/Canonical aendern | id, seoPathInfo, isCanonical, isDeleted |
seo_url_generate |
SEO URLs regenerieren | routeName, salesChannelId |
¶ Helfer-Tools
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
get_properties |
Produkt-Eigenschaften und Optionen | groupId |
get_manufacturers |
Hersteller/Brands auflisten | search, limit |
snippet_list |
Produkt-Snippets (Plugin-abhaengig) | activeOnly |
¶ Verwendung
¶ Beispiel-Workflows
Produkt anlegen:
"Lege ein neues Produkt an: Name 'ITH Tasche Fruehlingsblumen', Produktnummer 'ITH-FB-001', Preis 5.99 EUR, Kategorie Stickdateien."
Produktbeschreibung generieren:
"Generiere eine Beschreibung fuer das Produkt mit der Nummer ITH-FB-001."
Claude laedt das Produkt, erkennt den Stil (Kreativ fuer Stickdateien) und generiert eine passende Beschreibung.
SEO-Optimierung:
"Generiere SEO-Metadaten fuer das Produkt 'OXID Sitemap Modul' und speichere sie."
Content mit bestimmtem Stil:
"Generiere eine Beschreibung fuer Produkt XY im Stil 'b2b'."
Claude nutzt das angegebene Profil aus der content-profiles.json statt der automatischen Erkennung.
BFSG-Audit:
"Welche aktiven Produktbilder haben keinen Alt-Text? Erstelle mir eine Liste."
Cross-Selling einrichten:
"Welche Produkte wuerden gut als Zubehoer zum Produkt XY passen?"
Claude nutzt cross_selling_suggest, um Kategorie-Nachbarn zu analysieren und Empfehlungen zu geben.
Bestellstatistiken:
"Wie viele Bestellungen hatten wir im Januar 2026 und wie hoch war der Umsatz?"
Mail-Template bearbeiten:
"Zeig mir das Template fuer die Bestellbestaetigung und aendere den Betreff auf 'Danke fuer deine Bestellung Nr. {{ order.orderNumber }}'."
¶ Fehlerbehebung
¶ MCP Server laedt nicht
Symptom: Claude zeigt den Server nicht als verbunden an oder Tools sind nicht verfuegbar.
Pruefen:
- Ist der Build aktuell?
npm run buildim Projektverzeichnis ausfuehren - Stimmt der Pfad in der MCP-Konfiguration?
node /pfad/zu/dist/index.jsmuss direkt funktionieren - Ist Node.js >= 20 installiert?
node --versionpruefen - Existiert die
.env-Datei im richtigen Verzeichnis?
# Test ob der Server startet:
node /pfad/zu/dist/index.js
# Sollte auf stdin/stdout warten (kein Fehler)
¶ Authentifizierung fehlgeschlagen
Symptom: Fehlermeldung AUTH_FAILED oder Could not authenticate with Shopware.
Pruefen:
- Sind
SHOPWARE_CLIENT_IDundSHOPWARE_CLIENT_SECRETkorrekt? - Ist die Shopware-Integration aktiv (nicht deaktiviert)?
- Ist die Shop-URL erreichbar?
curl -s https://shop.example.com/api/oauth/tokentesten - HTTPS verwenden - HTTP wird mit einer Warnung akzeptiert, kann aber Probleme verursachen
OAuth2-Tokens werden automatisch gecacht und 60 Sekunden vor Ablauf erneuert. Bei persistenten Auth-Fehlern die Integration in Shopware pruefen.
¶ Tools reagieren nicht / Timeout
Symptom: Tool-Aufrufe dauern sehr lange oder brechen mit Timeout ab.
Pruefen:
- Shopware-Server erreichbar? Netzwerkverbindung testen
- Ist der Shop ueberlastet? (z.B. nach grossem Import)
- Timeout liegt bei 30 Sekunden pro Request - bei langsamen Servern kann das knapp werden
- Rate Limiting: Shopware hat eigene Rate Limits. Der MCP Server nutzt Exponential Backoff (max 3 Retries)
¶ Berechtigungsfehler
Symptom: API_ERROR mit Status 403 oder Forbidden.
Pruefen:
- Hat die Integration die richtigen Berechtigungen? (Siehe Abschnitt "Shopware-Integration einrichten")
- Fuer Schreiboperationen (Create, Update) braucht es Write-Rechte auf die jeweilige Entitaet
- Berechtigungen nach dem Aendern: Cache in Shopware leeren (
bin/console cache:clear)
¶ Falsche oder fehlende Daten
Symptom: Produkte/Kategorien werden nicht gefunden, obwohl sie existieren.
Pruefen:
- Stimmt die Sales-Channel-ID? Produkte muessen dem konfigurierten Sales Channel zugewiesen sein
- InMemory-Cache: Kategorien werden 1 Stunde gecacht. Server-Neustart leert den Cache
- Shopware IDs sind 32-Zeichen Hex-Strings (z.B.
b7d2554b0ce847cd82f3ac9bd1c0dfca)
¶ Content-Profile werden nicht geladen
Symptom: Eigene Stile werden nicht erkannt oder es kommen Validierungsfehler.
Pruefen:
- Ist die JSON-Datei syntaktisch korrekt?
node -e "JSON.parse(require('fs').readFileSync('content-profiles.json','utf8'))"testen - Verweist
defaultProfileauf ein existierendes Profil? - Verweisen alle
categoryMapping-Werte auf existierende Profile? - Hat jedes Profil alle Pflichtfelder (
tonality,addressing,structure,targetAudience,exampleIntro)? - Ist
addressingexakt"du"oder"Sie"(Gross-/Kleinschreibung beachten)? - Nach Aenderungen: MCP Server neu starten (Profile werden nur beim Start geladen)
¶ Technische Details
¶ Architektur
¶ Server-Verzeichnisstruktur
src/
├── index.ts # MCP Server Entry Point + Tool Dispatch
├── bootstrap.ts # Dependency Injection Setup
├── config/
│ ├── Configuration.ts # .env Laden und Validierung
│ ├── ContentProfilesSchema.ts # Zod-Schema fuer content-profiles.json
│ ├── ContentProfilesLoader.ts # Datei-Suche und Laden mit Fallback
│ └── ContentProfilesDefaults.ts # Eingebaute Standard-Profile
├── core/
│ ├── domain/ # Pure Domain Entities (13 Dateien)
│ └── services/ # Business Logic (12 Services + Tests)
├── application/
│ └── schemas/ # Zod Input Validation (11 Schema-Dateien)
├── infrastructure/
│ ├── shopware/ # OAuth2 Auth + HTTP Client
│ ├── cache/ # InMemory Cache mit TTL
│ └── logging/ # stderr Logging (MCP-konform)
├── tools/
│ ├── definitions.ts # Alle 43 Tool-Definitionen
│ └── handlers/ # Tool Handler (11 Dateien)
└── test/ # Test-Fixtures und Setup (MSW)
¶ Architektur-Diagramm
¶ MCP-Protokoll-Details
| Eigenschaft | Wert |
|---|---|
| Transport | stdio (stdin/stdout) |
| MCP Version | 1.0 |
| Serialisierung | JSON |
| Logging | stderr (keine stdout-Kontamination) |
| Tool Count | 43 |
¶ Sicherheitsfeatures
- Shopware ID Validation: Alle IDs werden als 32-Zeichen Hex-String validiert (verhindert Injection)
- OAuth2 Token Caching: Sichere Token-Verwaltung mit 60-Sekunden-Buffer vor Ablauf
- SSRF-Schutz: Media-Upload-URLs werden gegen private IP-Bereiche geprueft (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- Rate Limiting: Mail-Test-Versand auf 5/min pro Template und 10/min global begrenzt
- Timeout Protection: 30s Request Timeout, 15s OAuth Timeout
- Error Masking: Interne Fehlerdetails werden nicht an Claude exponiert (stattdessen hilfreiche Suggestions)
- Retry Safety: Exponential Backoff bei 429-Responses (max 3 Retries, 1s Basis)
- Config Validation: Content-Profile werden mit Zod vollstaendig validiert (Schema + referenzielle Integritaet)
¶ Caching-Strategie
| Daten | TTL | Begruendung |
|---|---|---|
| Kategorien | 1 Stunde | Aendern sich selten |
| Properties | 1 Stunde | Aendern sich selten |
| Hersteller | 1 Stunde | Aendern sich selten |
| Snippets | 5 Minuten | Koennen sich aendern |
| Einzelne Produkte | 5 Minuten | Moderate Aenderungsrate |
| Mail Templates | 10 Minuten | Selten geaendert |
| Bestellungen | Kein Cache | Immer aktuell benoetigt |
| Media | Kein Cache | Aktualitaet wichtig |
| Content-Profile | Einmalig beim Start | Nur bei Neustart aktualisiert |
Der InMemory-Cache hat ein Maximum von 500 Eintraegen und fuehrt alle 60 Sekunden ein Auto-Pruning abgelaufener Eintraege durch.
¶ FAQ
Was ist MCP?
MCP (Model Context Protocol) ist ein offener Standard von Anthropic, der es AI-Modellen wie Claude ermoeglicht, mit externen Diensten zu interagieren. Der MCP Server fungiert als Bruecke zwischen Claude und der Shopware Admin API.
Funktioniert der Server auch mit Shopware 5?
Nein. Der Server nutzt die Shopware 6 Admin API, die sich grundlegend von Shopware 5 unterscheidet. Eine Portierung ist nicht geplant.
Welche Node.js-Version brauche ich?
Mindestens Node.js 20. Die CI-Pipeline testet gegen Node.js 20 und 22.
Kann Claude damit Bestellungen aendern?
Nein. Die Bestell-Tools sind bewusst read-only. Bestellungen koennen nur gelesen und statistisch ausgewertet werden. Aenderungen an Bestellungen sollten manuell im Shopware Admin erfolgen.
Was passiert bei einem API-Fehler?
Der Server gibt strukturierte Fehlermeldungen mit Error-Code, Beschreibung und einer Suggestion zurueck. Bei temporaeren Fehlern (Rate Limiting, Token-Ablauf) wird automatisch ein Retry durchgefuehrt.
Funktioniert der Server mit Claude Desktop?
Ja. Die Konfiguration erfolgt ueber die claude_desktop_config.json (siehe Abschnitt Konfiguration). Der Server nutzt stdio-Transport und ist mit allen MCP-kompatiblen Clients kompatibel.
Werden Produkte sofort im Shop sichtbar?
Nein. Produkte werden immer als inaktiv erstellt. Du musst sie explizit ueber product_set_active aktivieren, nachdem du sie geprueft hast.
Wie funktioniert die Content-Stil-Erkennung?
Der Server liest die Kategorie-Breadcrumbs des Produkts und matched gegen das konfigurierte categoryMapping. Die Zuordnung und die Profile selbst koennen ueber eine content-profiles.json angepasst werden. Ohne Konfigurationsdatei werden die eingebauten Standard-Profile (Creative + Software) verwendet. Der Stil kann auch per style-Parameter manuell erzwungen werden.
Wie passe ich die Content-Profile an?
Kopiere content-profiles.example.json nach content-profiles.json, passe die Profile an und starte den MCP Server neu. Du kannst beliebig viele Profile definieren und Kategorien zuordnen. Details siehe Content-Profile konfigurieren.
Muss ich eine content-profiles.json erstellen?
Nein. Ohne Konfigurationsdatei verwendet der Server die eingebauten Standard-Profile (Creative und Software). Die Datei ist nur noetig, wenn du eigene Stile, Tonalitaeten oder Kategorie-Zuordnungen brauchst.
¶ Lizenz
MIT License - Lizenztext auf GitHub
¶ Support und Changelog
Repository: github.com/markus-michalski/claude-mcp-shopwareadmin
Issues: GitHub Issues
¶ Changelog
Siehe CHANGELOG.md auf GitHub fuer die vollstaendige Aenderungshistorie.