WooCommerce MCP open source: schreibgeschützter Shop-Zugriff für KI-Agenten

#WooCommerce MCP open source: schreibgeschützter Shop-Zugriff für KI-Agenten

Bei WooCommerce-zu-ERP-Projekten im DACH-Raum taucht in Kickoff-Calls dieselbe Frage auf: Kann die KI einfach den Shop prüfen? Die ehrliche Antwort lautet ja - wenn sie nichts kaputtmachen kann. Genau diese Einschränkung ist der Grund, warum wir woocommerce-mcp als Open Source geliefert haben: einen schlanken Model-Context-Protocol-(MCP-)Server, der Live-Fragen zu Produkten, Bestand, Bestellungen, Umsatz und Beiträgen über die offiziellen REST-APIs beantwortet - ohne Writes und ohne Plugin im Shop. Für Operations und Datenschutz ist das der pragmatische Einstieg: Lesen ja, Mutieren nein.

Dieser Artikel ist der Release- und Betriebsleitfaden für das veröffentlichte Paket. Wenn Sie einen eigenen Server von Grund auf entwerfen müssen (einschließlich mutierender Tools oder Workers-Deployment), nutzen Sie den Begleitleitfaden MCP-Server für WooCommerce aufbauen. Für das kommerzielle Programm siehe MCP-Server-Entwicklung und WooCommerce-ERP-Integration.

#TL;DR

• Paket: @wppoland/woocommerce-mcp auf npm (CLI-Binary heißt weiterhin woocommerce-mcp).
• Registry: io.github.wppoland/woocommerce-mcp im offiziellen MCP Registry.
• Fünf Read-only-Tools über WooCommerce- / WordPress-REST - nur Read-Keys.
• Kein Shop-Plugin. MIT, TypeScript, Node 18+.
• Nutzen Sie das, wenn Agenten Fakten aus Katalog und Bestellungen brauchen; bauen Sie Custom-MCP, wenn Writes oder ERP-spezifische Tools nötig sind.

#Warum wir einen Read-only-MCP-Server geliefert haben

MCP gibt einem LLM-Host (Claude Desktop, Cursor, ein eigener Agent) eine typisierte tools/list-Oberfläche, statt das Modell zu zwingen, sich /wp-json/wc/v3/-Pfade auszudenken. Das ist nützlich. Es ist auch gefährlich, wenn jedes Tool Bestand, Rückerstattungen oder Kundendaten mutieren kann.

Bei ERP-Sync-Arbeit sehen wir zwei Fehlermodi häufiger als clevere Prompt-Fehler:

1. Überverkauf an Black Friday, weil ein Write-Pfad mit einem Lager-Feed in eine Race Condition gelaufen ist.
2. Verseentliche Statusänderungen, wenn ein Agent beim Debuggen „hilfreich“ Bestellungen als abgeschlossen markiert hat.

Read-only-MCP repariert kein schlechtes ERP-Design. Es entfernt eine Klasse versehentlicher Writes aus der Agent-Ebene. Der Shop bleibt die maßgebliche Quelle über WooCommerce REST. Der Agent fragt nur.

Im deutschen B2B-WooCommerce-Alltag - Großhandel mit Netto-Preislisten, Händlerkonten und getrennten ERP-Stammdaten - ist das besonders relevant: Operative Teams wollen in natürlicher Sprache wissen, ob Kampagnen-SKUs schon auf Null stehen, ohne wp-admin zu öffnen und ohne einem Agenten Schreibrechte zu geben, die DSGVO-relevante Bestellmetadaten und ggf. Kundendaten berühren könnten. Viele DACH-Shops betreiben parallel einen B2C-Kanal und einen Händler-Login; ein Read-only-Agent, der nur Katalog und Bestellstatus liest, ist dort oft der erste akzeptable Kompromiss zwischen Operations und Datenschutz.

Die Protokollentscheidung haben wir in MCP vs REST: wann was gewinnt dokumentiert, die Auth-Oberfläche in MCP-Authentifizierungsmuster. Dieses Release ist die konkrete Binary, die Sie heute installieren können.

#Was geliefert wurde (Juli 2026)

Version 0.1.1 ist das Installationsziel. Version 0.1.0 existierte kurz als fehlgeschlagener Registry-Stub - eine kollidierende Legacy-_auth-Zeile in lokalem ~/.npmrc hat den Publish kaputt gemacht. Ignorieren Sie 0.1.0.

#Warum der npm-Name @wppoland/woocommerce-mcp ist

Der Name ohne Präfix woocommerce-mcp ist auf npm gesperrt (E403), nachdem eine andere Partei ihn unpublished hat. Wir veröffentlichen als @wppoland/woocommerce-mcp. Nutzen Sie diesen Namen für npm install / npx. Das bin-Feld in package.json stellt weiterhin den Befehl woocommerce-mcp bereit, sodass Claude-Desktop- und Cursor-Configs denselben Binary-Namen behalten.

Das mcpName in package.json lautet io.github.wppoland/woocommerce-mcp. Dieser String muss mit dem MCP-Registry-server.json-Feld name übereinstimmen, damit die Ownership-Verifikation beim Publish mit der offiziellen mcp-publisher-CLI gelingt.

#Tool-Oberfläche

Alles wird an der MCP-Grenze validiert und ruft dann REST auf. In diesem Paket gibt es keinen Pfad, der Produkte anlegt, Bestand aktualisiert, Bestellungen erstattet oder Plugins installiert.

#Fragen, die diese Tools tatsächlich beantworten

• Welche SKUs stehen vor einer Kampagne auf Nullbestand?
• Was haben wir letzten Monat netto verkauft - so wie der Shop es bereits meldet?
• Was waren die letzten zwanzig Bestellungen im Status processing?
• Ist der Shop mit den ausgegebenen Keys erreichbar?

Das sind die Fragen, die in ERP-Integrations-Stand-ups auftauchen. Es sind auch die Fragen, die keine Schreibrechte brauchen.

#Installation und Konfiguration

#Voraussetzungen

• Node.js 18 oder neuer
• Ein WooCommerce-Shop unter HTTPS
• Möglichkeit, REST-API-Keys mit Berechtigung Lesen anzulegen

#Installation

npm install -g @wppoland/woocommerce-mcp
# or one-shot:
npx @wppoland/woocommerce-mcp

Aus dem Quellcode:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build

#Umgebungsvariablen

Keys anlegen unter WooCommerce → Einstellungen → Erweitert → REST-API → Schlüssel hinzufügen. Berechtigung: Lesen. Wenn Ihnen jemand Lesen/Schreiben „nur für alle Fälle“ reicht, lehnen Sie ab. Das Paket braucht keine Write-Scopes, und ungenutzte Write-Scopes sind ein Incident, der auf ein kompromittiertes Laptop wartet.

search_posts funktioniert gegen die öffentliche WordPress-REST-API ohne Woo-Keys. Das ist nützlich für Content-Agenten; es ist trotzdem kein Grund, Admin-Cookies dem MCP-Host preiszugeben.

#Claude-Desktop- / Cursor-Skizze

Registrieren Sie einen stdio-Server, der die Binary mit den drei Env-Vars startet. Exakte JSON-Formen variieren je nach Client-Version; die Invariante lautet: stdio, Env vom Host injiziert, keine Secrets im Chat-Transkript.

Nach dem Connect etwas Falsifizierbares fragen: „Wie ist der Bestand für SKU X?“ Wenn der Agent eine Zahl erfindet, ohne einen Tool-Aufruf, ist Ihr Client nicht wirklich verdrahtet. Wenn er list_products oder get_product aufruft und den Shop-Wert zurückgibt, sind Sie für den Smoke-Test fertig.

#Beispiel-Fragment für Claude Desktop

Client-Config-Formate ändern sich; behandeln Sie das als Form, nicht als Dauervertrag:

{
  "mcpServers": {
    "woocommerce-mcp": {
      "command": "woocommerce-mcp",
      "env": {
        "WP_URL": "https://shop.example.com",
        "WC_CONSUMER_KEY": "ck_replace_me",
        "WC_CONSUMER_SECRET": "cs_replace_me"
      }
    }
  }
}

Bevorzugen Sie einen vollständigen Pfad zur Binary aus npm root -g, wenn der PATH der Desktop-App dünner ist als der Terminal-PATH. Cursor und andere Hosts nutzen ähnliche stdio- und Env-Muster.

#Fehlerbehebung bei der Installation

Wenn npm view @wppoland/woocommerce-mcp version 404 liefert, während npm access das Paket noch listet, sind Sie im Broken-Stub-Zustand, den wir bei 0.1.0 getroffen haben. Version bumpen, Legacy-registry.npmjs.org/:_auth aus ~/.npmrc entfernen falls vorhanden, und erneut publishen. Sagen Sie Händlern nicht, eine Version zu installieren, die Sie nicht npm pack können.

#Sicherheitsmodell (klare Sprache)

1. Keys bleiben auf dem MCP-Host, nicht als Plugin im Shop und nicht in den Modellgewichten.
2. Nur Leseberechtigung am WooCommerce-Key.
3. Nur HTTPS für WP_URL.
4. Behandeln Sie die MCP-Client-Maschine als Produktion, wenn sie Live-Keys hält - dieselbe Latte wie ein CI-Secret-Store.
5. Keys rotieren, wenn ein Laptop das Unternehmen verlässt oder ein Contractor-Auftrag endet.

MCP löst Auth nicht magisch. Die längere Behandlung steht unter MCP-Authentifizierungsmuster. Für dieses Paket ist der konservative Default lokales stdio mit Read-Keys, kein öffentlicher HTTP-MCP-Endpoint im offenen Internet.

#Bedrohungshinweise aus echten Reviews

• Laptop-Diebstahl: Read-Keys leaken Katalog- und Bestellmetadaten. Das ist weiterhin DSGVO-relevant: Bestell-IDs, SKUs und Zeitstempel können personenbezogene oder personenbeziehbare Daten sein, sobald sie mit Kundendaten verknüpft werden. Festplatte verschlüsseln, kurzlebige Keys für Demos, Widerruf beim Offboarding. In deutschen Unternehmen erwarten Informationssicherheit und Datenschutz oft auch eine dokumentierte Aufbewahrungsfrist für MCP-Host-Logs - behandeln Sie Tool-Argumente wie Produktionslogs.
• Prompt Injection über Produktbeschreibungen: Ein bösartiger Produkttitel lässt dieses Paket nicht schreiben, kann aber die Rede des Modells steuern. Unvertrauten Katalogtext nicht ohne Mensch in der Schleife in risikoreiche Automatisierung stecken.
• Confused Deputy über geteilte MCP-Hosts: Ein Claude-Desktop-Profil mit Keys für Shop A und Shop B ist ein Unfall, der wartet. Getrennte Profile oder getrennte Maschinen - besonders relevant, wenn Agenturen mehrere DACH-Mandanten auf demselben Laptop betreuen.
• Log-Leakage: Manche Hosts loggen Tool-Argumente. Gehen Sie davon aus, dass SKUs und Bestell-IDs in Logs erscheinen; Retention entsprechend konfigurieren und prüfen, ob das Logging-Konzept mit Ihrer AV-Vereinbarung und den TOMs zusammenpasst.

Nichts davon ist ein Grund, MCP zu vermeiden. Es sind Gründe, den Host wie Produktion zu behandeln. Wenn Ihr Unternehmen bereits ein Verzeichnis von Verarbeitungstätigkeiten führt: tragen Sie den MCP-Host als Verarbeitungsmittel ein, sobald Live-Keys und Bestellmetadaten darauf landen - nicht erst nach dem ersten Incident.

#Wo das in ERP- und KI-Programme passt

Die Arbeit von WPPoland für EU-Kunden verdrahtet oft WooCommerce mit Großhandels-APIs und ERPs. Agenten kommen in diesen Stack, wenn Operations-Teams natürliche Sprachantworten wollen, ohne wp-admin zu öffnen. Read-only-MCP ist der erste sichere Slice:

• Pre-Sync-Checks: „Sind wir bei den Kampagnen-SKUs schon ausverkauft?“
• Post-Sync-Audits: „Sehen die Bestellungen von gestern aus wie die ERP-Rechnungsanzahl?“
• Content-Ops: „Welche Beiträge erwähnen die neue Kollektion?“ über search_posts

Wenn Agenten Bestellungen vorschlagen oder Rückerstattungen entwerfen sollen, verlassen Sie dieses Paket und bauen einen Custom-Server mit expliziten mutierenden Tools, Idempotenz-Keys und menschlichen Freigabe-Gates. Dieser Pfad ist der Build-Leitfaden plus typisierte Katalog-Tools mit Zod.

Für Shops, die schon unter Plugin-Wildwuchs oder KI-gebautem Theme-Debt ersticken, Core Web Vitals und Bestands-Wahrheit reparieren, bevor Sie Agenten hinzufügen. MCP rettet weder einen TTFB von 1,8 s noch einen Katalog, der dem Lager widerspricht.

#Wie sich das von gehosteten WordPress-MCP-Experimenten unterscheidet

WordPress.com und verwandte Ökosysteme explorieren MCP-Oberflächen für Managed Hosting. Diese Programme sind wertvoll - und sie sind nicht dasselbe Artefakt wie ein selbst gehosteter stdio-Server, den Sie auf Ihre WooCommerce-REST-Keys zeigen. Self-hosted MCP hält Credentials und Traffic auf Infrastruktur Ihrer Wahl. Hosted MCP hält Komfort zu den Bedingungen des Hosts. Bewusst wählen; Feature-Parität nicht annehmen.

Glama und ähnliche MCP-Directories können das GitHub-Repo oder den Registry-Eintrag indexieren. Behandeln Sie Third-Party-Directories als Discovery, nicht als Sicherheitsgrenze. Source of Truth für die Installation bleiben npm + GitHub + der offizielle MCP-Registry-Name.

#Vergleich: Open-Source-Paket vs. Custom-MCP

#Publishing-Hinweise für Maintainer

Wenn Sie forken oder einen eigenen MCP-Server publishen:

1. mcpName in package.json setzen, passend zum Registry-Namespace (für GitHub-Auth: io.github.<org>/<name>).
2. server.json-description bei höchstens 100 Zeichen halten - das offizielle Registry lehnt längere Strings mit HTTP 422 ab.
3. Die mcp-publisher-Binary aus modelcontextprotocol/registry releases nutzen, nicht ein zufälliges npm-Paket namens publisher.
4. Bevorzugen Sie npm-Namen unter einem @scope, den Sie kontrollieren; Namen ohne Präfix können nach Unpublish dauerhaft gesperrt bleiben.

Das Description-Limit haben wir beim ersten Registry-Publish-Versuch auf die harte Tour gelernt. Validierung mit mcp-publisher validate vor publish spart eine Runde.

#Operative Checkliste

• @wppoland/[email protected] (oder neuer) installiert
• WooCommerce-Key ist Read-only
• WP_URL ist HTTPS und gehört zum Shop der Keys
• Client nutzt stdio (oder einen anderen Transport, den Sie bewusst gehärtet haben)
• Smoke-Test nutzt eine echte SKU und einen echten Zeitraum
• Secrets landen nicht in Tickets oder Chat-Logs
• Team weiß: Dieses Paket kann nicht erstatten oder nachfüllen - Writes an Menschen / ERP eskalieren
• MCP-Host-Logs und Retention sind mit DSGVO-/TOM-Vorgaben abgestimmt (besonders bei B2B-Shops mit Händlerdaten)

#Interne Cluster-Links

• Build-Pfad: MCP-Server für WooCommerce aufbauen
• Protokollwahl: MCP vs REST
• Auth: MCP-Authentifizierungsmuster
• Typisierte Tools: Typisierte Katalog-Tools mit Zod für MCP
• Migration: Bestehende WordPress-API auf MCP migrieren
• Service: MCP-Server-Entwicklung
• Commerce: WooCommerce-ERP-Integration

#Praxisnotizen aus Kundenprojekten

Bei einem DACH-B2B-Shop mit Netto-Preislisten und Händlerkonten (Katalog im mittleren fünfstelligen SKU-Bereich, Stammdaten im ERP) war die Demo, die Operations überzeugte, kein Chat-Widget im Shop-Frontend. Es war Claude Desktop auf dem Ops-Laptop, der vor dem Newsletter fragte: „Welche Kampagnen-SKUs stehen schon auf Null?“ Die Demo bestand den Security-Review nur, weil MCP den Bestand nicht „korrigieren“ konnte, als das Modell eine Schreibaktion vorschlug.

Bei einem Sync Woo → deutsches ERP (Bestand und Preise) lautete die gefährliche Anfrage: „Markiere die als abgeschlossen, wenn sie bezahlt aussehen.“ Genau diese Tool-Klasse bietet dieses Open-Source-Paket nicht an. Der Agent kann processing-Bestellungen listen; ein Mensch oder ein dedizierter ERP-Job schließt sie ab.

Im DACH-B2B-Umfeld kommt oft noch die Frage nach Logging und Nachweisbarkeit: Wer hat wann welche Bestell-ID über den Agenten abgefragt? Self-hosted stdio hält diese Spur auf Ihrer Maschine - und damit in Ihrer Verantwortung. Planen Sie Key-Rotation und Log-Retention mit, bevor Live-Keys auf Laptops von Freelancern landen. Für Agenturen mit mehreren Mandanten gilt zusätzlich: getrennte MCP-Profile pro Shop, keine gemeinsamen Env-Dateien im Slack, und ein schriftlicher Widerrufsprozess, wenn der Auftrag endet.

Ein weiteres Muster aus deutschen Projekten: Marketing will den Agenten „kurz“ auf Staging zeigen, Operations hat aber dieselben Read-Keys wie Produktion kopiert. Staging-Keys ausstellen, Staging-WP_URL setzen, und den Smoke-Test dort fahren - bevor jemand Live-Bestellungen in einem Demo-Chat landen lässt.

Wenn Ihr Shop noch Application Passwords mit vollen Capabilities für „temporäre Skripte“ nutzt, rotieren Sie die, bevor Sie einen MCP-Host auf Produktion zeigen. Read-Keys für diesen Server sind günstig auszustellen und günstig zu widerrufen.

#Was wir in v0.x nicht tun

• Keine Write-Tools im Open-Source-Default-Branch.
• Kein verpflichtendes Shop-Plugin.
• Keine Behauptung, MCP ersetze WooCommerce REST für Partner-Integrationen.
• Keine konkreten Preise für Implementierungsarbeit - Projekte werden individuell angeboten über MCP-Server-Entwicklung.

Feature-Requests, die zum Read-only-Mandat passen (Refunds-Zusammenfassung, Coupon-Status, Kunden-Lookup ohne PII-Dumps), sind offene Gespräche auf GitHub. Feature-Requests der Form „einfach update_product hinzufügen“ werden mit Verweis auf den Custom-Build-Leitfaden geschlossen.

#Messen, ob der Agent-Pfad sich lohnt

Bevor Sie über Read-only-Tools hinausgehen, messen Sie drei Dinge über zwei Wochen:

1. Wie oft öffnen Menschen wp-admin nur, um eine Bestands- oder Bestellfrage zu beantworten. Liegt die Zahl nahe Null, ist MCP eine Neuheit. Ist sie täglich, zahlen Lese-Tools sich in Aufmerksamkeit zurück.
2. Wie oft widersprechen diese Antworten dem ERP. MCP liefert WooCommerce-Wahrheit, nicht Lager-Wahrheit. Wenn die divergieren, Sync zuerst reparieren (WooCommerce-ERP-Integration).
3. Wie oft bittet jemand den Agenten, Zustand zu ändern. Diese Frequenz ist Ihr Roadmap-Signal für einen Custom-Mutating-Server - kein Grund, dieses Paket aufzuweichen.

GEO- und AEO-Programme brauchen zitierbare, strukturierte Antworten. Ein MCP-Tool-Aufruf, der Bestand zurückgibt, ist zuverlässiger als ein Modell, das von einer gescrapten HTML-Seite rät. Koppeln Sie den Agent-Pfad mit On-Site-Entities und FAQ-Schema auf Ihren kommerziellen Seiten, damit öffentliche KI-Systeme und private Agenten nicht unterschiedliche Produktgeschichten erfinden. Für DACH-Händler heißt das konkret: dieselbe SKU-Wahrheit im Shop, im ERP und in der Agent-Antwort - und dokumentierte Read-only-Grenzen, die Sie in einem Security-Review vorzeigen können.

#Fazit

@wppoland/woocommerce-mcp ist die kleinste nützliche MCP-Oberfläche, der wir vor einem Live-WooCommerce-Shop vertrauen: fünf Lese-Tools, offizielle REST darunter, MIT, veröffentlicht auf npm und im MCP Registry. Installieren Sie es, wenn Agenten Shop-Fakten brauchen. Bauen Sie einen Custom-Server, wenn Agenten Shop-Aktionen brauchen.

Start hier: https://www.npmjs.com/package/@wppoland/woocommerce-mcp - dann Read-Keys verdrahten, eine Smoke-Frage stellen und Writes aus dem Agent-Pfad heraushalten, bis das Programm dafür bereit ist.