¶ Inhaltsverzeichnis
- Überblick
- Features
- Anwendungsfälle
- Anforderungen
- Installation
- Konfiguration
- Content-Profile konfigurieren
- Verfügbare Tools
- Verwendung
- Fehlerbehebung
- Technische Details
- FAQ
- Lizenz
- Support und Changelog
¶ Überblick
claude-mcp-shopwareadmin ist ein MCP Server (Model Context Protocol), der Claude die direkte Steuerung der Shopware 6 Admin API ermöglicht. Mit 43 spezialisierten Tools deckt er den kompletten Shop-Management-Workflow ab: von der Produkterstellung über Content-Generierung und SEO-Optimierung bis hin zu Bestellübersichten und BFSG-konformem Media-Management.
Dieser MCP Server ermöglicht Claude die direkte Interaktion mit deinem Shopware 6 Shop - Produkte anlegen, Beschreibungen generieren, SEO optimieren, Bestellungen prüfen und Media verwalten, ohne manuelles Copy-Paste oder Browser-Wechsel.
¶ Kern-Philosophie
- User legt Struktur an (Produkte, Varianten, Bilder im Shopware Admin)
- Claude übernimmt Content (Texte, SEO, Verwaltungsaufgaben)
- Safety First - Produkte werden IMMER inaktiv angelegt
- Type-Safe - TypeScript + Zod-Validierung überall
¶ Features
- 43 MCP Tools für umfassende Shop-Verwaltung
- Produktverwaltung: Erstellen, Lesen, Aktualisieren, Suchen, Aktivieren/Deaktivieren
- Automatische Content-Generierung mit Stil-Erkennung (Kreativ vs. Software)
- Konfigurierbare Content-Profile über externe JSON-Datei (eigene Stile, Tonalität, 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-Prüfung)
- Bestellübersichten 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)
¶ Anwendungsfälle
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 Prüfen).
Content-Generierung: "Schreibe eine Produktbeschreibung für Produkt XY" - Claude erkennt automatisch den Stil (Kreativ für Stickdateien, Professionell für 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-Änderungen. Siehe Content-Profile konfigurieren.
SEO-Optimierung: "Optimiere die SEO-Daten für alle Produkte in der Kategorie Software" - Claude generiert Meta-Titel, Beschreibung und Keywords pro Produkt.
BFSG-Compliance: "Prüfe welche Produktbilder keinen Alt-Text haben" - Claude führt 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 Entitäten haben (Produkte, Kategorien, Mail-Templates, Media, etc.). Für reine Leseoperationen genügen 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 |
Währungs-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 für Wiki.js-Verlinkungen |
CACHE_TTL_CATEGORIES |
Nein | 3600000 |
Cache-TTL für Kategorien (ms, 1 Stunde) |
CACHE_TTL_PROPERTIES |
Nein | 3600000 |
Cache-TTL für Properties (ms, 1 Stunde) |
CACHE_TTL_SNIPPETS |
Nein | 300000 |
Cache-TTL für Snippets (ms, 5 Minuten) |
LOG_LEVEL |
Nein | info |
Log-Level: debug, info, warn, error |
¶ Shopware-Integration einrichten
- Shopware Admin öffnen > Einstellungen > System > Integrationen
- Neue Integration erstellen
- Namen vergeben (z.B. "Claude MCP Server")
- Folgende Mindest-Berechtigungen vergeben:
| Entität | 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 | Steuersätze lesen |
| currency | Ja | Nein | Währungen 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 übernehmen
Verwende separate Integrationen für verschiedene Umgebungen (Staging/Produktion). Teile niemals Client Secrets über unsichere Kanäle.
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 über eine externe JSON-Datei konfigurierbar. Du kannst eigene Stile, Tonalitäten, Anrede-Formen und Kategorie-Zuordnungen definieren - ganz ohne Code-Änderungen.
¶ Konzept
Der MCP Server nutzt Content-Profile, um Produktbeschreibungen und SEO-Texte im passenden Stil zu generieren. Jedes Profil definiert Tonalität, Anrede, Textstruktur und Zielgruppe. Über ein Kategorie-Mapping wird automatisch das richtige Profil anhand der Produkt-Kategorie ausgewählt.
Bisher waren diese Profile fest im Code verankert. Ab v1.1.0 können sie über eine content-profiles.json frei angepasst werden.
¶ Suchpfad-Priorität
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 vollständig validiert. Fehlerhafte Dateien führen 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 | Tonalität der Texte (z.B. "Persönlich, warm") |
profiles.*.addressing |
"du" / "Sie" |
Anrede-Form |
profiles.*.structure |
string[] | Textstruktur-Vorgaben für die Generierung |
profiles.*.targetAudience |
string | Zielgruppe für den generierten Content |
profiles.*.exampleIntro |
string | Beispiel-Einstieg als Orientierung für Claude |
profiles.*.includeSnippets |
boolean | Ob Produkt-Textbausteine eingebunden werden sollen. Erfordert das Plugin Produkt-Textbausteine |
categoryMapping |
object | Zuordnung Kategoriename → Profilname |
Alle Werte in
categoryMappingmüssen auf existierende Profile verweisen. DerdefaultProfilemuss ebenfalls existieren. Zod prüft das beim Laden automatisch.
¶ Beispiel: Eigenes Profil hinzufügen
Du kannst beliebig viele Profile erstellen. Hier ein Beispiel für 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 verfügbar. Der style-Parameter in product_generate_content und category_generate_content akzeptiert dann auch "b2b".
¶ Verfügbare Tools
¶ Übersicht
| 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 über alle Produkte | query, limit |
Produkte werden bei der Erstellung IMMER als inaktiv angelegt. Das ist ein bewusstes Sicherheitsfeature - erst prüfen, dann aktivieren.
¶ Content-Generierung
| Tool | Beschreibung | Wichtige Parameter |
|---|---|---|
product_generate_content |
Generierungs-Prompt für 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 | Tonalität | Anrede |
|---|---|---|---|
| Stickdateien | creative | Persönlich, warm, emotional | "du" |
| Genähtes | creative | Persönlich, warm, emotional | "du" |
| 3D-Druck | creative | Persönlich, warm, emotional | "du" |
| Software | software | Professionell, sachlich | "Sie" |
Der Stil kann mit dem Parameter style auch manuell erzwungen werden. Eigene Profile können über die content-profiles.json hinzugefügt 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 für 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 für die Einhaltung des deutschen Barrierefreiheitsstärkungsgesetzes. Alle Produktbilder MÜSSEN 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 für 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 ändern | 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-abhängig) | activeOnly |
¶ Verwendung
¶ Beispiel-Workflows
Produkt anlegen:
"Lege ein neues Produkt an: Name 'ITH Tasche Frühlingsblumen', Produktnummer 'ITH-FB-001', Preis 5.99 EUR, Kategorie Stickdateien."
Produktbeschreibung generieren:
"Generiere eine Beschreibung für das Produkt mit der Nummer ITH-FB-001."
Claude lädt das Produkt, erkennt den Stil (Kreativ für Stickdateien) und generiert eine passende Beschreibung.
SEO-Optimierung:
"Generiere SEO-Metadaten für das Produkt 'OXID Sitemap Modul' und speichere sie."
Content mit bestimmtem Stil:
"Generiere eine Beschreibung für 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 würden gut als Zubehör 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 für die Bestellbestätigung und ändere den Betreff auf 'Danke für deine Bestellung Nr. {{ order.orderNumber }}'."
¶ Fehlerbehebung
¶ MCP Server lädt nicht
Symptom: Claude zeigt den Server nicht als verbunden an oder Tools sind nicht verfügbar.
Prüfen:
- Ist der Build aktuell?
npm run buildim Projektverzeichnis ausführen - Stimmt der Pfad in der MCP-Konfiguration?
node /pfad/zu/dist/index.jsmuss direkt funktionieren - Ist Node.js >= 20 installiert?
node --versionprüfen - 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.
Prüfen:
- 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 prüfen.
¶ Tools reagieren nicht / Timeout
Symptom: Tool-Aufrufe dauern sehr lange oder brechen mit Timeout ab.
Prüfen:
- Shopware-Server erreichbar? Netzwerkverbindung testen
- Ist der Shop überlastet? (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.
Prüfen:
- Hat die Integration die richtigen Berechtigungen? (Siehe Abschnitt "Shopware-Integration einrichten")
- Für Schreiboperationen (Create, Update) braucht es Write-Rechte auf die jeweilige Entität
- Berechtigungen nach dem Ändern: Cache in Shopware leeren (
bin/console cache:clear)
¶ Falsche oder fehlende Daten
Symptom: Produkte/Kategorien werden nicht gefunden, obwohl sie existieren.
Prüfen:
- Stimmt die Sales-Channel-ID? Produkte müssen 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.
Prüfen:
- 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 Änderungen: 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 geprüft (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 vollständig validiert (Schema + referenzielle Integrität)
¶ Caching-Strategie
| Daten | TTL | Begründung |
|---|---|---|
| Kategorien | 1 Stunde | Ändern sich selten |
| Properties | 1 Stunde | Ändern sich selten |
| Hersteller | 1 Stunde | Ändern sich selten |
| Snippets | 5 Minuten | Können sich ändern |
| Einzelne Produkte | 5 Minuten | Moderate Änderungsrate |
| Mail Templates | 10 Minuten | Selten geändert |
| Bestellungen | Kein Cache | Immer aktuell benötigt |
| Media | Kein Cache | Aktualität wichtig |
| Content-Profile | Einmalig beim Start | Nur bei Neustart aktualisiert |
Der InMemory-Cache hat ein Maximum von 500 Einträgen und führt alle 60 Sekunden ein Auto-Pruning abgelaufener Einträge durch.
¶ FAQ
Was ist MCP?
MCP (Model Context Protocol) ist ein offener Standard von Anthropic, der es AI-Modellen wie Claude ermöglicht, mit externen Diensten zu interagieren. Der MCP Server fungiert als Brücke 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 ändern?
Nein. Die Bestell-Tools sind bewusst read-only. Bestellungen können nur gelesen und statistisch ausgewertet werden. Änderungen 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 zurück. Bei temporären Fehlern (Rate Limiting, Token-Ablauf) wird automatisch ein Retry durchgeführt.
Funktioniert der Server mit Claude Desktop?
Ja. Die Konfiguration erfolgt über 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 über product_set_active aktivieren, nachdem du sie geprüft 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 können über 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 nötig, wenn du eigene Stile, Tonalitäten 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 für die vollständige Änderungshistorie.