Medusa.js und KI-Agenten: Custom Commerce schneller bauen

Die meisten Shop-Plattformen wurden nie dafür gebaut, von einem Coding-Agenten bedient zu werden. Medusa.js v2 ist die Ausnahme, und dieser Text zeigt, warum. Die anderen setzen voraus, dass ein Mensch vor einem Partnerverzeichnis sitzt, Glue-Code von Hand schreibt und Screenshots von Admin-Masken deutet. Setzen Sie Claude Code vor so eine Plattform, spüren Sie die Reibung in den ersten zehn Minuten. Mit Medusa kehrt sich das Bild um: Der Agent liest den Quellcode, fragt die Dokumentation über einen offiziellen MCP-Server ab und liefert an einem Nachmittag ein echtes Feature.

Dieser Text ist die deutsche Ausgabe meines englischen Guides, zugeschnitten auf die Fragen, die mir Mittelständler stellen: Wo passen KI-Agenten wirklich in den E-Commerce-Stack, was ist Marketing und was ist belastbar? Alle Versionen und Befehle sind am 27. August 2026 gegen die offiziellen Quellen geprüft. Und weil ich selbst einen Medusa-Marketplace mit 10.000 Produkten und 50 Händlern produktiv betreibe, schreibe ich hier über meinen Arbeitsalltag, nicht über eine Demo.

Was ist Medusa.js v2 und warum ist es 2026 relevant?

Medusa.js ist ein MIT-lizenziertes, quelloffenes Headless-Commerce-Framework in TypeScript. Die v2-Architektur, Stand August 2026 in Version 2.19.0 (Release vom 13. August, parallel auf npm bestätigt), zerlegt Commerce-Funktionen in isolierte Module und stellt Store-, Admin- und Workflow-APIs bereit, auf denen Sie jedes Frontend bauen. Konkret heißt das: der flexibelste Commerce-Motor, den Sie derzeit selbst hosten können.

Drei Bausteine prägen die Arbeit damit. Die Commerce-Module – Warenkorb, Bestellungen, Produkte, Zahlungen, Lager und weitere – sind einzeln austauschbar; wer den Warenkorb behalten, aber den Bestand über SAP führen will, kann genau das tun. Das Framework mit API-Routen, Datenmodellen und Workflows trägt Ihre Geschäftslogik; die Workflow-Engine mit Kompensationsfunktionen pro Schritt ist der unterschätzte Star der v2. Und das Admin-Dashboard, eine eingebaute React-App, nimmt Widgets und eigene Ansichten auf – Lieferantenportale und Freigabe-Flows entstehen ohne separates Frontend-Projekt.

Produktiv läuft das Ganze längst nicht mehr nur bei Start-ups: Eight Sleep baut darauf, ebenso Redington, Indiens größter IT-Distributor.

Warum funktioniert Medusa so gut mit KI-Coding-Agenten?

Weil vier Eigenschaften zusammentreffen, die es bei kommerziellen Plattformen in dieser Kombination nicht gibt: Der Code ist offen, typisiert, vorhersagbar strukturiert und maschinell abfragbar.

• Offen: Der komplette Quellcode liegt auf GitHub. Wenn Claude Code nicht weiterweiß, liest es die Implementierung statt zu raten.
• Typisiert: TypeScript wirkt als Leitplanke. Halluziniert der Agent eine Methode, schlägt der Compiler Alarm.
• Vorhersagbar: Jede API-Route liegt unter src/api/<pfad>/route.ts, jeder Workflow ist eine Folge von createStep-Aufrufen, jedes Admin-Widget eine React-Komponente mit defineWidgetConfig. Der Agent erfindet keine Struktur, er folgt ihr.
• Abfragbar: Die Dokumentation auf docs.medusajs.com ist über einen MCP-Endpunkt maschinell erreichbar – dazu gleich mehr.

Ein Beispiel aus meiner Arbeit macht es konkret. Im März habe ich eine Hamburger Modemarke bei der Evaluierung begleitet: Medusa gegen einen Shopify-Plus-Ausbau. Vier Stunden Zeitfenster, Aufgabe: ein individuelles Pflegehinweis-Feld, sichtbar im Admin, im Storefront und in einem nachgelagerten PIM. Der Shopify-Partner hatte sechs Wochen veranschlagt. Mit Medusa und Claude Code stand der funktionierende Prototyp – Datenmodell, Migration, Admin-Widget, Store-Route – nach knapp drei Stunden Pair-Programming; rund 70 Prozent der Tipparbeit kam vom Agenten. Das Fazit der CTO danach: Die Magie sei nicht die KI, sondern ein Framework, das die KI arbeiten lässt.

Genau das ist das Argument. Medusa gewinnt nicht mit spektakuläreren KI-Features, sondern weil seine Architektur die strukturierte, musterfolgende Arbeit belohnt, in der Agenten stark sind. Warum viele Agentenprojekte trotzdem scheitern, habe ich im Beitrag zu KI-Agenten in Produktion aufgeschrieben – die Review-Disziplin bleibt Ihre Aufgabe, egal wie gut das Framework ist.

Welches offizielle KI-Tooling liefert Medusa mit?

Medusa liefert als einziger mir bekannter Commerce-Anbieter einen kompletten, offiziellen Werkzeugkasten für agentengestützte Entwicklung: einen MCP-Server, Claude-Code-Plugins, eine fürs Terminal gebaute Cloud-CLI und einen Cloud Development Agent.

Der Medusa MCP Remote Server ist ein Streamable-HTTP-Endpunkt unter https://docs.medusajs.com/mcp. Jeder MCP-fähige Client – Claude Code, Cursor, VS Code – verbindet sich damit und erhält Zugriff auf die aktuelle Dokumentation samt Schritt-für-Schritt-Anleitungen. Der Server ist Medusa-Cloud-Nutzern vorbehalten und authentifiziert per OAuth oder Personal Access Token; in Claude Code genügt claude mcp add --transport http medusa https://docs.medusajs.com/mcp. Der Effekt: Der Agent arbeitet nicht mehr mit veraltetem Trainingswissen, sondern fragt die Referenz von heute ab.

Die Agent-Skills unter medusajs/medusa-agent-skills sind der offizielle Claude-Code-Plugin-Marktplatz. Stand August 2026 listet die Doku drei Plugins: medusa-dev für Backend-, Admin- und Storefront-Entwicklung, learn-medusa als interaktives Tutorial und ecommerce-storefront mit Storefront-Mustern. Andere Agenten übernehmen dieselben Skills per npx skills add medusajs/medusa-agent-skills.

Die Cloud-CLI (@medusajs/mcloud) macht Deployments, Build- und Laufzeit-Logs aus dem Terminal abrufbar – gebaut, um vom Agenten aufgerufen zu werden: mcloud logs --search "OrderPlacedHandler" statt Dashboard-Klickerei. Der Cloud Development Agent kennt Projekt, Deployments und Umgebungsvariablen und untersucht fehlgeschlagene Deploys auf Zuruf.

Wie verbinden Sie Claude Code mit Medusa in fünf Minuten?

Der schnellste Weg von null zum arbeitsfähigen Setup sind fünf Terminal-Befehle, alle am 27. August 2026 gegen die Doku geprüft:

# 1. Medusa-Projekt anlegen
npx create-medusa-app@latest mein-shop
cd mein-shop

# 2. Medusa starten (Terminal offen lassen)
npm run dev

# 3. In einem zweiten Terminal: Claude Code installieren und starten
npm install -g @anthropic-ai/claude-code
claude

# 4. In Claude Code: Medusa-Plugins anbinden
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install medusa-dev@medusa

# 5. Prüfen
/plugin

Listet /plugin das Paket medusa-dev unter „Installed“, steht die Verbindung. Ein kurzer Test-Prompt („Beschreibe die Projektstruktur“) sollte src/modules, src/workflows, src/api und src/admin referenzieren – dann arbeitet der Agent auf dem echten Projekt. Das Grundsetup von Medusa selbst, inklusive Docker und erster Produkte, zeigt demnächst mein deutsches Schritt-für-Schritt-Tutorial hier im Blog.

Wie sieht ein echtes Feature mit Agent aus?

Das Muster ist immer gleich: Datenmodell erweitern, Admin-Oberfläche ergänzen, Workflow schreiben, Diff prüfen. Der Agent tippt, Sie spezifizieren und reviewen. Ein Beispiel aus einem Projekt dieses Frühjahrs: ein supplier_email-Feld pro Produkt, damit die Fulfillment-Strecke automatisch das richtige Lager benachrichtigt – Datenmodell-Erweiterung per Module Link, Admin-Widget in der passenden Injection Zone, ein Subscriber auf order.fulfilled und ein Workflow mit drei createStep-Aufrufen samt Kompensationsfunktionen. Mit dem früheren Shopify-Plus-Setup des Kunden hatte die Partneragentur für Vergleichbares sieben Wochen gebraucht; mit Medusa und Claude Code waren es zwei Arbeitstage, größtenteils Review und Tests.

Die ehrliche Fußnote dazu: Das Tooling reift noch. Der OAuth-Flow des MCP-Servers zickte bei mir anfangs, die Log-Streams der Cloud-CLI hängen unter Last gelegentlich nach. Ich empfehle den Stack trotzdem, weil die Architektur stimmt und das Tempo der Verbesserungen hoch ist – aber poliert wie ein seit Jahren gereiftes Admin-Panel ist es nicht.

Wann lohnt sich die Kombination – und wann nicht?

Die Kombination lohnt sich, wenn Sie Individualisierung brauchen, die Mietplattformen nicht wirtschaftlich abbilden. Vier Muster sehe ich in Projekten immer wieder:

• B2B-Portale mit Firmenhierarchien, kundenindividuellen Preislisten und Freigabeprozessen – klassisches Terrain für Module und Workflows.
• Commerce als Orchestrierungsschicht über einem bestehenden ERP: SAP oder Dynamics führt Bestand und Preise, Medusa choreografiert die Prozesse davor.
• Datensouveränität als harte Anforderung – EU-Hosting oder On-Premise, mit einem Stack, der vollständig Ihnen gehört.
• Marketplaces mit mehreren Händlern, Auftragssplitting und Provisionslogik; auf dieser Architektur läuft auch mein eigenes Projekt – den Aufbau beschreibt mein Marktplatz-Leitfaden.

Für einen kleinen Standard-Shop mit Standard-Checkout ist die Kombination dagegen Overkill; da bleibe ich bei meiner Empfehlung aus dem Kostenvergleich mit Shopify, und auch der Vergleich mit Shopware zieht dieselbe Grenze.

Für Entscheider ist der Effekt auf die Wirtschaftlichkeit das eigentliche Argument: KI-Agenten senken genau den Kostenblock, der bei Medusa-Projekten dominiert – die Entwicklungszeit. Jede Stunde, die der Agent an Boilerplate, Migrationen und Admin-Widgets übernimmt, verschiebt die Rechnung weiter zugunsten des eigenen Stacks. Was das für Ihre Branche konkret heißt, skizziere ich auf der Seite zu E-Commerce-Projekten; alle Artikel zu beiden Themen finden Sie im Themenbereich E-Commerce und im Themenbereich KI-Agenten.

Wenn Sie herausfinden wollen, ob Ihr Use Case auf die richtige Seite dieser Grenze fällt: Buchen Sie ein kostenloses Erstgespräch – 30 Minuten, eine ehrliche Einschätzung, keine Folien.