lightspeed-x-mcp

Ein Model Context Protocol-Server für Lightspeed X (Lightspeed Retail POS, die Plattform, die früher als Vend bekannt war). Er gibt Claude oder jedem MCP-Client schreibgeschützten Zugriff auf Verkäufe, Lagerbestand, Produkte und Kunden deines Stores – und übernimmt die Aggregation für dich: Umsatz, Stückzahlen, Wareneinsatz (COGS), Bruttogewinn, Marge, Rabatte, durchschnittlicher Warenkorbwert und Warenkorbgröße, gruppiert nach jeder beliebigen Dimension, die du angibst.

Von Natur aus schreibgeschützt. Jedes Tool sendet GET-Anfragen. Es gibt keinen Codepfad in diesem Server, der etwas in deinem Konto erstellen, aktualisieren oder löschen könnte. Du kannst ihn also bedenkenlos auf ein laufendes Einzelhandelsgeschäft richten.

"What sold best yesterday?"                → lightspeed_sales_report
"Revenue by store last week"               → lightspeed_sales_report, group_by: outlet
"Which SKUs need reordering?"              → lightspeed_inventory_report, status: reorder_needed
"What are our busiest hours?"              → lightspeed_sales_report, group_by: hour
"Margin by brand this month"               → lightspeed_sales_report, group_by: brand
"Pull up invoice 162220"                   → lightspeed_list_sales

Warum es das gibt

Die Lightspeed-X-API ist ein Überbleibsel aus der Vend-Ära und hat einige scharfe Kanten, die naive Clients entweder langsam oder stillschweigend falsch arbeiten lassen. Dieser Server übernimmt das, damit das Modell sich nicht darum kümmern muss:

Wie die Umsatzberechnung hergeleitet wird

Verifiziert anhand von 200 aufeinanderfolgenden Live-Verkäufen. Jeder einzelne stimmte mit dem eigenen totals.price des Verkaufs auf zwei Cent überein:

line revenue excl tax = line_items[].pricing.total        (net of discount, already x quantity)
line COGS             = line_items[].pricing.cost_total
line discount given   = line_items[].pricing.discount_total
line tax              = line_items[].tax.total

Drei weitere Prüfungen an Live-Daten, alle exakt:

• Die Summe des Tagesumsatzes über eine Woche entspricht der Gesamtsumme der Woche.

• Die Zeile eines Outlets in einem Bericht mit group_by: outlet entspricht demselben Bericht, erneut ausgeführt mit dem serverseitigen Filter dieses Outlets.

• Die Summe der nach Zahlungsart getenderten Beträge entspricht dem Umsatz inklusive Steuer.

Related MCP server: mcp-pdv-demo

Installation

Option 1: als Claude-Code-Plugin (empfohlen)

Drei Befehle, kein Klonen, kein Build, keine zu bearbeitenden Pfade:

/plugin marketplace add genvjacobc/lightspeed-x-mcp
/plugin install lightspeed-x@lightspeed-x-mcp
/lightspeed-x:setup

Der dritte Befehl führt ein gebündeltes Setup-Skill aus, das dich durch die Beschaffung eines Tokens führt, es an der richtigen Stelle speichert und die Verbindung gegen dein Live-Konto verifiziert, bevor es dir mitteilt, dass es funktioniert hat.

Das Plugin enthält außerdem ein reports-Skill, damit Claude weiß, welches Tool welche Art von Einzelhandelsfrage beantwortet und wie die zurückgegebenen Zahlen zu lesen sind.

Anmeldedaten liegen unter ${CLAUDE_PLUGIN_DATA}/credentials.env, einem benutzerbezogenen Verzeichnis, das Plugin-Updates übersteht. Es wird nichts zwischen Maschinen oder Teammitgliedern geteilt.

Beachte, dass /plugin uninstall dieses Verzeichnis löscht – eine Deinstallation und Neuinstallation bedeutet also, dass die Einrichtung erneut ausgeführt werden muss. Das Token selbst bleibt in Lightspeed aktiv; widerrufe es dort, wenn du es nicht mehr benötigst.

Option 2: als eigenständiger MCP-Server

git clone https://github.com/genvjacobc/lightspeed-x-mcp.git
cd lightspeed-x-mcp
npm install
npm run build

Erfordert Node 18 oder neuer.

Ein API-Token erhalten

Im Lightspeed-X-Backoffice: Setup → Persönliche Tokens → Persönliches Token hinzufügen. Kopiere es, bevor du den Dialog schließt; es wird nur einmal angezeigt.

Zwei Einschränkungen, die du kennen solltest, bevor du einen Rollout planst:

• Nur Admin-Benutzer können persönliche Tokens erstellen, und Lightspeed beschränkt die Funktion auf Plus-Tarife. Wenn „Persönliche Tokens“ nicht unter Setup erscheint, muss jemand mit Admin-Zugriff das Token für dich erstellen.

• Lightspeed bietet keine schreibgeschützten Tokens an. Ein Token trägt alle Berechtigungen des Benutzers, der es erstellt hat. Dieser Server sendet ausschließlich GET-Anfragen, aber das Token selbst ist eine Allzweck-Anmeldeinformation – behandle es also wie ein Passwort und widerrufe es über denselben Bildschirm, falls es durchsickert.

Prüfen, ob es funktioniert

npm run doctor

Dies validiert deine Anmeldedaten, ruft die Live-API auf und benennt die genaue Ursache jedes Fehlers. Sowohl eine falsche Store-Domain als auch ein ungültiges Token liefern HTTP 401 von Lightspeed zurück, daher meldet der Doctor beide Möglichkeiten, statt zu raten.

Konfiguration

Kopiere .env.example nach .env und fülle deinen Store aus:

LIGHTSPEED_DOMAIN=mystore
LIGHTSPEED_TOKEN=your_personal_token

LIGHTSPEED_DOMAIN akzeptiert ein nacktes Präfix (mystore), einen Host (mystore.retail.lightspeed.app) oder eine vollständige URL. Alle drei führen zum selben Ziel.

Mehrere Stores. Jedes Paar aus LIGHTSPEED_<NAME>_DOMAIN + LIGHTSPEED_<NAME>_TOKEN definiert ein Konto namens <name> (in Kleinbuchstaben). Tools akzeptieren dann ein optionales account-Argument:

LIGHTSPEED_NORTH_DOMAIN=northstore
LIGHTSPEED_NORTH_TOKEN=token_for_north
LIGHTSPEED_SOUTH_DOMAIN=southstore
LIGHTSPEED_SOUTH_TOKEN=token_for_south
LIGHTSPEED_DEFAULT_ACCOUNT=north

Bereits in der Umgebung vorhandene Werte haben immer Vorrang vor der .env-Datei, sodass ein Host, der Anmeldedaten direkt injiziert, Vorrang hat.

Bei Claude Code registrieren (nur eigenständiger Pfad)

Überspringe diesen Schritt, wenn du das Plugin installiert hast; das Plugin registriert den Server selbst.

claude mcp add lightspeed-x -s user -- node /absolute/path/to/lightspeed-x-mcp/dist/index.js

Oder füge es manuell zu deiner Konfiguration hinzu:

{
  "mcpServers": {
    "lightspeed-x": {
      "command": "node",
      "args": ["/absolute/path/to/lightspeed-x-mcp/dist/index.js"],
      "env": {
        "LIGHTSPEED_DOMAIN": "mystore",
        "LIGHTSPEED_TOKEN": "your_personal_token"
      }
    }
  }
}

Für Claude Desktop kommt derselbe Block in claude_desktop_config.json.

Verifiziere lokal mit dem MCP Inspector:

npm run inspect

Tools

lightspeed_sales_report

Das Hauptwerkzeug. Aggregiert einen Datumsbereich und gruppiert ihn.

| Outlet          |   Revenue | Units | Sales | Basket value | Gross profit | Margin |
| --------------- | --------: | ----: | ----: | -----------: | -----------: | -----: |
| South Lincoln   | $3,401.60 |   193 |    91 |       $37.38 |    $2,342.35 |  68.9% |
| York            | $3,222.86 | 159.2 |    73 |       $44.15 |    $2,238.77 |  69.5% |

lightspeed_list_sales

Einzelne Transaktionen, neueste zuerst, mit optionaler Erweiterung der Positionen. Zum Eintauchen in einen einzelnen Beleg, zur Prüfung einer Summe oder zum Ansehen von Retouren. Filter auf outlet_id, customer_id und min_total.

lightspeed_inventory_report

Lagerbestand, verknüpft mit Produkt- und Outlet-Namen, mit Einzelhandels- und Einstandswert des Bestands im Regal.

status ist das Argument, das zählt:

group_by rollt auf product, outlet, category, brand oder supplier hoch – so beantwortest du die Frage „Wie viel Lagerwert steckt in jeder Kategorie“.

lightspeed_search_products

Freitextsuche über Name, Variantenname, SKU und Handle, mit Filtern für Marke / Lieferant / Kategorie / Tag. Die Suche läuft lokal gegen den gecachten Katalog, weil der eigene Such-Endpunkt der API schlecht rankt – die Ergebnisse sind also exakte Teilstring-Treffer.

lightspeed_get_product

Vollständige Details zu einem Produkt per ID oder exakter SKU, einschließlich Lagerbestand pro Outlet und berechneter Marge.

lightspeed_search_customers / lightspeed_get_customer

Kunden per E-Mail nachschlagen (an die API übergeben) oder per Name, Telefon oder Kundencode (lokal abgeglichen). Gibt die UUID zurück, die die Verkaufstools als customer_id-Filter akzeptieren. Dies liefert personenbezogene Daten; gehe entsprechend damit um.

lightspeed_list_outlets / lightspeed_list_registers / lightspeed_list_accounts

Löst Store-Namen in die Outlet-UUIDs auf, die die Berichtsfilter erwarten, listet POS-Kassen einschließlich E-Commerce-Registern auf und zeigt, welche Konten der Server erreichen kann. lightspeed_list_accounts gibt niemals Tokens zurück.

lightspeed_list_reference_data

Ein Tool für brands, suppliers, product_categories, tags, customer_groups, payment_types, promotions, taxes und users. Verwenden Sie es, um die exakte Schreibweise einer Marke oder Kategorie zu erhalten, bevor Sie einen Bericht danach filtern.

lightspeed_api_get

Notausstieg für jeden Endpunkt ohne speziell entwickeltes Tool: /consignments, /price_books, /serial_numbers usw. Es wird ausschließlich GET ausgeführt.

Leistung und Grenzen

Berichte werden dadurch geprägt, dass Verkäufe serverseitig nicht nach Datum gefiltert werden können.

Der Großteil eines Kaltaufrufs besteht aus den ~30 Einzelzeilen-Sonden, die den Datumsbereich lokalisieren. Diese Sonden werden pro Konto gespeichert, sodass der zweite Bericht in einer Sitzung normalerweise keine benötigt. Katalog-, Standort-, Kassen-, Benutzer- und Inventarscans werden 15 Minuten lang zwischengespeichert.

Um alles schnell zu halten: Übergeben Sie outlet_id, wenn Sie nur einen Store betreffen, und bevorzugen Sie enge Datumsbereiche. LIGHTSPEED_MAX_SALES (Standard 200.000) begrenzt einen einzelnen Aufruf, und das Tool teilt Ihnen klar mit, wenn es abschneidet, anstatt stillschweigend eine Teilantwort zurückzugeben.

Ein ehrlicher Hinweis. Da der Datumsbereich über die Version ermittelt wird, kann ein Verkauf, der vor dem Bereich erstellt, aber danach bearbeitet wurde, übersehen werden. LIGHTSPEED_SEEK_MARGIN_DAYS (Standard 1) legt fest, wie weit vor dem Bereich die Suche ansetzt, und eine Erhöhung erweitert das Sicherheitsnetz auf Kosten des Scannens weiterer Datensätze. Dies ist einer API inhärent, die nicht nach Datum filtert, und keine hier gewählte Abkürzung.

Konfigurationsreferenz

Entwicklung

npm run dev      # run from source with tsx
npm run build    # compile to dist/
npm run inspect  # MCP Inspector against the built server
npm run doctor   # credentials + live connectivity check
npm run validate-plugin  # validate the plugin manifests

src/
  index.ts            entry point, env loading, tool registration
  config.ts           account discovery from the environment
  lib/
    client.ts         HTTP client, retry, version pagination
    version-seek.ts   date to version binary search
    sales.ts          sale fetching and metric aggregation
    catalog.ts        cached product, outlet, register, inventory lookups
    time.ts           timezone-aware day boundaries
    format.ts         Markdown table rendering, tool results
  tools/              one file per tool group

Tools geben Markdown-Tabellen statt rohem JSON zurück: Ein Modell liest eine ausgerichtete Tabelle zuverlässiger als einen tiefen JSON-Block, bei einem Bruchteil der Tokens. Die zugrunde liegenden Zahlen befinden sich auch auf structuredContent für programmatische Aufrufer.

Zwei Konventionen, die Sie beibehalten sollten, wenn Sie beitragen:

• Werfen Sie niemals aus einem Tool-Handler. Fehler werden als isError-Ergebnisse zurückgegeben. Der guard()-Wrapper erzwingt dies.

• Verwenden Sie niemals console.log. Stdout transportiert JSON-RPC-Frames. Diagnosen gehen an console.error.

Repository-Struktur

.claude-plugin/     plugin + marketplace manifests
.mcp.json           MCP server declaration used by the plugin path
skills/setup/       guided connection walkthrough
skills/reports/     how to answer retail questions with these tools
src/                TypeScript source
dist/               compiled output, committed so plugin installs need no build

dist/ wird absichtlich in git nachverfolgt, da die Installation des Claude-Code-Plugins keinen Build-Schritt ausführt und der kompilierte Server mit dem Repository ausgeliefert werden muss. Führen Sie npm run build aus, bevor Sie eine Quellcodeänderung committen, und erhöhen Sie version in package.json, .claude-plugin/plugin.json und .claude-plugin/marketplace.json gemeinsam, wenn Sie veröffentlichen.

Lizenz

MIT. Siehe LICENSE.

Nicht verbunden mit oder unterstützt von Lightspeed Commerce.