vex: die Vendure CLI und der MCP-Server für die Admin API
vex spricht die Vendure Admin GraphQL API - aus dem Terminal oder als MCP-Server, damit Claude es für Sie tut. Es liest das Schema Ihrer Instanz inklusive der Felder aus Ihren eigenen Plugins, verwaltet mehrere Umgebungen und macht einmal gebaute Queries wiederholbar. Voraussetzung ist Vendure 3.6 oder neuer.
Drei schlechte Wege, die Admin API zu bedienen
Wer an einer Vendure-Instanz etwas ändern will, das die Admin-UI nicht anbietet, hat bisher die Wahl zwischen drei unbefriedigenden Optionen. Klicken in der Admin-UI: gut für den Einzelfall, nicht wiederholbar und für die Felder Ihrer eigenen Plugins oft gar nicht vorgesehen. GraphQL von Hand in curl oder Postman: funktioniert, aber Sie schreiben jedes Selection Set neu, hantieren mit Auth-Headern und raten, wie das Feld in Ihrem Custom-Plugin wirklich heißt. Oder Sie bauen sich ein Skript, das genau eine Sache kann und danach in einem Ordner verstaubt.
Alle drei Wege haben dasselbe Loch: Niemand von ihnen kennt Ihr Schema. Vendure-Projekte weichen genau da vom Standard ab, wo die Arbeit liegt - eigene Typen, eigene Mutationen, eigene Permissions. vex holt sich die SDL Ihrer Instanz, cached sie und arbeitet damit: beim Feld-Picker, bei der Introspection und bei der Fehlermeldung, wenn dem API-Key eine Permission fehlt.
Voraussetzung: Vendure 3.6 oder neuer
vex authentifiziert sich über API-Keys. Die gibt es erst ab Vendure 3.6. Auf 3.5 oder älter läuft vex nicht - das vor dem Install prüfen. Außerdem nötig: Node.js 20 oder neuer.
- API-Key-Auth in der Vendure-Config aktivieren:
authOptions: { tokenMethod: ['cookie', 'bearer', 'api-key'] } - Im Vendure-Dashboard zu Settings > API Keys gehen.
- Key erzeugen, die nötigen Rollen bzw. Permissions zuweisen und den Key kopieren - er wird nur einmal angezeigt.
Der Key wird bei jedem Request im Header vendure-api-key gesendet.
So funktioniert es
Einmal einrichten, danach ist jede Umgebung einen Befehl entfernt. vex speichert alles unter ~/.vendure-vex/: Environments, gecachte Schemas, Fragments und gespeicherte Operationen.
Environment anlegen
vex env add dev fragt interaktiv nach URL und API-Key und validiert die Angaben direkt, indem es das Schema abholt. Mehrere Instanzen laufen nebeneinander, vex env status sagt Ihnen pro Umgebung, ob der Endpoint erreichbar und der Key akzeptiert ist.
Query bauen oder speichern
Im interaktiven Builder wählen Sie Operation und Felder, vex fragt die Variablen mit passender Typumwandlung ab und zeigt das erzeugte GraphQL-Dokument. Mit --save wird daraus eine benannte Operation, die Sie später per vex run mit anderen Variablen wiederholen.
Claude andocken (optional)
vex mcp install schreibt eine .mcp.json in Ihr Projekt und verknüpft das Verzeichnis mit der gewählten Umgebung. Danach arbeitet Claude über dieselben Operationen, die Sie im Terminal nutzen.
Quickstart
Global installieren, eine Umgebung anlegen, loslegen - alles Weitere ist optional.
npm install -g @spaceparrots/vexvex env add dev
vex env status dev
vex build -q customers
vex build -q contents --save ContentsPublished
vex run ContentsPublished --var "options={\"take\":5}"
vex schema fetchvex mcp installErst schauen, dann schreiben? vex mcp config gibt das Snippet nur aus.
Was vex kann
Kein Framework, kein Dashboard - ein Kommandozeilen-Werkzeug für Leute, die die Admin API ohnehin schon benutzen.
Mehrere Umgebungen mit Health-Check
Dev, Staging und Produktion liegen als benannte Environments nebeneinander, umschaltbar per vex use <env>. vex env status prüft Erreichbarkeit des Endpoints, Akzeptanz des API-Keys und Zustand des gecachten Schemas.
Schema-aware, inklusive Custom-Plugin-Feldern
vex holt die SDL Ihrer Instanz und legt sie pro Umgebung ab, inklusive der Typen, Queries und Mutationen, die Ihre eigenen Plugins ergänzen. Introspection läuft danach lokal: Typen beschreiben, Custom Fields auflisten, Operationen nachschlagen.
Interaktiver Query-Builder
Operation auswählen, Felder im Picker anhaken, Variablen mit korrekter Typumwandlung eingeben - vex zeigt das erzeugte Dokument und führt es aus. Mit --dry-run sehen Sie das Ergebnis, bevor irgendetwas an den Server geht.
Fragments und gespeicherte Operationen
Fragments sind benannte Feldauswahlen, die Sie über mehrere Operationen wiederverwenden. Gespeicherte Operationen halten das komplette Dokument samt Standard-Variablen fest und laufen per vex run erneut, einzelne Variablen überschreibbar.
Typisierte Resource-Commands und Asset-Uploads
Customers, Products, Orders, Channels, Zones und Tax haben fertige list/get/create/update/delete-Befehle plus resource-spezifische Aktionen wie order transition oder zone add-members. Lokale Dateien lädt vex asset upload hoch - den GraphQL-Multipart-Request übernimmt vex.
Escape Hatch und Permission-Diagnose
vex query und vex mutate führen beliebiges GraphQL aus, wenn kein fertiger Befehl passt. Scheitert etwas an FORBIDDEN oder UNAUTHORIZED, benennt vex die abgelehnte Operation und schlägt die wahrscheinlich fehlenden Permission-Werte vor; vex schema permissions listet alle, auch die aus Plugins.
Vendure mit Claude verwalten: der MCP-Server
Ohne Argumente gestartet läuft vex als MCP-Server über stdio - genau das, was MCP-Clients erwarten. Claude bekommt beim Handshake Server-Instructions mit, kennt also die Reihenfolge von typisierten Tools, Schema-Discovery und rohem GraphQL, bevor der erste Aufruf passiert. Das gecachte Schema liegt zusätzlich als MCP-Resource vendure://schema/<envName> bereit.
Full-Mode
Standardmodus, 15 Tools. Jede Entity-Domäne ist ein einzelnes Action-Dispatch-Tool: vex_customers, vex_products, vex_orders, vex_channels, vex_zones, vex_tax, vex_assets, dazu Setup, Schema-Discovery, rohes GraphQL, Fragments und gespeicherte Operationen. Ein Aufruf sieht aus wie vex_products mit { "action": "get", "id": "5" }.
Lean-Mode
Mit VEX_TOOLS=lean in der MCP-Client-Config registriert vex nur das universelle Interface: vex_setup, vex_current_env, vex_refetch_schema, vex_query, vex_mutate, vex_schema. Claude steuert Vendure dann über Schema-Discovery plus rohes GraphQL.
Warum das die Token-Kosten betrifft
Tool-Definitionen sind always-on: Name, Beschreibung und JSON-Schema jedes registrierten Tools stehen in jedem Request im Kontext, egal ob das Tool benutzt wird. Deshalb bündelt vex ganze Domänen in je ein Action-Dispatch-Tool statt in ein Tool pro Operation, und deshalb gibt es Lean-Mode: weniger Komfort, kleinster Fußabdruck pro Session. MCP-Antworten sind kompaktes JSON; VEX_PRETTY_JSON=1 formatiert sie lesbar und kostet rund 30 Prozent mehr Tokens.
Erstell mir eine Dummy-Bestellung für das Produkt "shoes".
Claude prüft, ob das Produkt existiert, legt es notfalls an, sucht oder erstellt einen Kunden, erzeugt einen Draft Order und fügt Positionen hinzu - die MCP-Tools verkettet es selbst.
Wann vex passt, und wann nicht
Passt, wenn
- Sie regelmäßig Dinge an einer Vendure-Instanz tun, die die Admin-UI nicht anbietet oder die zu oft anfallen, um sie zu klicken.
- Ihre Instanz Custom Plugins mit eigenen Typen, Mutationen oder Permissions hat und Sie deren Felder nicht jedes Mal nachschlagen wollen.
- Sie mehrere Umgebungen betreiben und sichergehen müssen, gegen welche Sie gerade arbeiten.
- Sie Claude oder einen anderen MCP-Client an Ihren Shop lassen wollen, aber mit definierten Tools statt mit freihändigem HTTP.
Passt nicht, wenn
- Sie die Storefront-API ansprechen wollen: vex arbeitet ausschließlich gegen die Admin API.
- Ihre Instanz auf Vendure 3.5 oder älter läuft - ohne API-Key-Auth gibt es keinen Weg hinein.
- Sie eine beliebige andere GraphQL-API bedienen wollen: vex ist auf Vendure zugeschnitten, nicht auf GraphQL allgemein.
- Sie eine grafische Oberfläche für nicht-technische Kolleginnen und Kollegen suchen - dafür ist die Admin-UI da, und sie ist dafür besser.
vex, Admin-UI oder GraphQL von Hand
Es gibt kein direktes Gegenstück zu vex. Die echten Alternativen sind die Admin-UI und selbst geschriebenes GraphQL - beide haben Situationen, in denen sie die bessere Wahl sind.
| Kriterium | vex | Admin-UI | Rohes GraphQL |
|---|---|---|---|
| Schema-Kenntnis inkl. Custom Fields | Holt und cached die SDL Ihrer Instanz, Custom-Plugin-Typen inklusive | Zeigt nur, was die UI dafür vorgesehen hat | Sie kennen das Schema oder Sie introspizieren es selbst |
| Wiederholbarkeit | Gespeicherte Operationen und Fragments, per vex run erneut ausführbar | Jeder Durchlauf ist Handarbeit | Wiederholbar, sofern Sie Dokumente und Variablen selbst verwalten |
| Multi-Environment | Benannte Environments, Projekt-Links, Health-Check per Befehl | Pro Instanz eine eigene URL und ein eigener Login | Sie jonglieren URLs und Header von Hand |
| KI-Steuerbarkeit | MCP-Server mit 15 Tools, im Lean-Mode 6 | Nicht vorgesehen | Nur über selbst gebaute Anbindung |
| Einstiegshürde | Node.js, Terminal, ein Setup-Schritt | Am niedrigsten: einloggen und klicken, auch ohne GraphQL-Kenntnis | Niedrig im Setup, hoch im Wissen |
| Überblick und Sichtprüfung | Textausgabe, JSON oder Tabelle | Deutlich besser: Listen, Detailansichten, Vorschauen | Rohes JSON |
Fehlt ein Befehl? Dann bauen Sie ihn ein.
Ich habe vex gebaut, um wiederkehrende Handgriffe an Vendure zu automatisieren und Prüfungen an einer Instanz reproduzierbar zu machen, statt sie jedes Mal neu zusammenzuklicken.
vex deckt die Domänen ab, die ich selbst am häufigsten brauche. Ihre Instanz sieht anders aus: eigene Plugins, eigene Mutationen, eigene Abläufe. Wenn ein Resource-Command fehlt, ein Custom-Feld nicht sauber durchläuft oder Ihnen im MCP-Modus ein Tool fehlt, machen Sie ein Issue auf oder schicken Sie direkt einen Pull Request. MIT-Lizenz, kein CLA.
Häufige Fragen zu vex
vex ist eine Open-Source-CLI und zugleich ein MCP-Server für die Vendure Admin GraphQL API. Im Terminal verwalten Sie damit Produkte, Kunden, Bestellungen, Channels, Zonen, Tax und Assets; als MCP-Server angebunden übernimmt Claude dieselben Operationen. Das Paket heißt @spaceparrots/vex, steht unter MIT-Lizenz und liegt auf npm.
Vendure 3.6 oder neuer. vex authentifiziert sich mit API-Keys, und die wurden erst in 3.6 eingeführt. Auf älteren Versionen gibt es keinen unterstützten Weg, vex zu betreiben.
Erweitern Sie in Ihrer Vendure-Config authOptions.tokenMethod um 'api-key', sodass dort ['cookie', 'bearer', 'api-key'] steht. Gehen Sie danach im Dashboard auf Settings > API Keys, legen Sie einen Key an und weisen Sie ihm die Rollen mit den nötigen Permissions zu. Der Key wird nur einmal angezeigt, kopieren Sie ihn sofort. vex sendet ihn anschließend im Header vendure-api-key.
Ja. vex mcp install schreibt eine .mcp.json in Ihr Projekt, danach steht vex als MCP-Server bereit. Sie formulieren die Aufgabe in normaler Sprache, Claude verkettet die passenden Tools, etwa Produkt suchen, Kunden anlegen, Draft Order erstellen, Positionen hinzufügen.
Ja, das ist einer der Gründe für vex. Es holt die SDL Ihrer laufenden Instanz und cached sie pro Umgebung, also stehen die Typen, Queries, Mutationen und Permissions Ihrer Plugins dem Feld-Picker, der Introspection und den MCP-Tools zur Verfügung. Für Custom-Mutationen ohne eigenen Befehl gibt es vex query und vex mutate.
Full-Mode ist die Voreinstellung und registriert 15 MCP-Tools, inklusive typisierter Tools für Kunden, Produkte, Bestellungen und die übrigen Domänen. Lean-Mode über VEX_TOOLS=lean registriert nur 6 Tools: Setup, Environment-Info, Schema-Refetch, Schema-Discovery und rohes Query bzw. Mutate. Weniger Tool-Definitionen bedeuten weniger Kontext pro Session, dafür arbeitet Claude mehr über Discovery und selbst formuliertes GraphQL.
Ja. Umgebungen liegen benannt in ~/.vendure-vex/config.json, umschaltbar per vex use <env>. Welche gilt, entscheidet vex in dieser Reihenfolge: explizites --env, dann die Variable VEX_ENV, dann ein Projekt-Link für das aktuelle Verzeichnis, dann die global aktive Umgebung. vex status sagt Ihnen jederzeit, welche gerade greift und warum.
Nichts. vex ist Open Source unter MIT-Lizenz und wird über npm installiert: npm install -g @spaceparrots/vex. Sie brauchen Node.js 20 oder neuer und eine Vendure-Instanz ab 3.6.
vex ausprobieren
Ein npm-Install, ein vex env add, und Sie sprechen mit Ihrer Admin API - vorausgesetzt, Ihre Instanz läuft auf Vendure 3.6 oder neuer.
vex entsteht bei SpaceParrots, nebenbei zur täglichen Vendure-Arbeit. Wenn Sie nicht nur ein Werkzeug, sondern Unterstützung am Projekt selbst brauchen: Vendure-Beratung und -Entwicklung.