Toast MCP Server

Ein schreibgeschützter Model Context Protocol-Server für die Toast POS-API. Er ermöglicht einem KI-Assistenten, Fragen zu Ihrem Restaurant zu beantworten und Verkaufs-, Arbeits- und Kassenberichte direkt aus Live-Toast-Daten zu erstellen.

Er schreibt niemals in Toast. Der HTTP-Client sendet ausschließlich GET-Anfragen; der einzige POST im Code ist der Authentifizierungsaufruf, den Toast zum Erstellen eines Tokens benötigt, und er ist in src/auth.ts isoliert. Der Smoke-Test bestätigt dies.

Was Sie fragen können

Sobald die Verbindung steht, funktionieren Fragen wie diese:

• „Wie haben wir letzte Woche im Vergleich zur Vorwoche abgeschnitten?"

• „Was waren unsere Top-20-Artikel nach Nettoumsatz im Juli, und wie ist der Durchschnittspreis jedes einzelnen?"

• „Schlüsseln Sie die Verkäufe nach Stunde für letzten Samstag auf – wann ist unser eigentlicher Abendansturm?"

• „Wie ist unser Verhältnis von Bargeld zu Karte in diesem Monat, und wie viel haben wir an Kartenverarbeitungsgebühren bezahlt?"

• „Welche Rabatte werden am häufigsten genutzt, und um wie viel?"

• „Zeigen Sie mir alle Stornierungen der letzten zwei Wochen mit Grund und wer gearbeitet hat."

• „Wie hoch war die Arbeitszeit als Prozentsatz des Nettoumsatzes letzten Monat, nach Mitarbeiter?"

• „Was ist gerade ausverkauft (86'd)?"

• „Finden Sie die 340-Dollar-Bestellung von Freitagabend und zeigen Sie mir, was darauf war."

• „Wie sind unsere Öffnungszeiten sonntags, und welche Speisemöglichkeiten haben wir konfiguriert?"

Related MCP server: Shopify MCP Server

Voraussetzungen

• Node.js 20 oder neuer (entwickelt und getestet auf Node 22).

• Toast-API-Anmeldedaten. Für ein Restaurant, das über seine eigenen Daten berichtet, ist das richtige Produkt Standard API Access, das von Natur aus schreibgeschützt und self-service ist:

  1. Gehen Sie in Toast Web zu Integrationen → Toast API-Zugriff → Anmeldedaten verwalten.

  2. Erstellen Sie einen Anmeldedatensatz, benennen Sie ihn (z. B. mcp-reporting) und wählen Sie die unten aufgeführten Lese-Berechtigungen.

  3. Kopieren Sie die Client-ID und das Client-Secret – das Secret wird nur einmal angezeigt.

  Wenn Ihr Konto diese Option nicht hat, ist sie Teil von Restaurant Management Essentials; Ihr Toast-Ansprechpartner kann sie aktivieren. Partnerintegrationen erhalten Anmeldedaten stattdessen vom Toast-Integrationsteam.

Zu aktivierende Berechtigungen

Nur orders:read, config:read und restaurants:read werden für die Kernverkaufsberichte benötigt. Der Server degradiert elegant, wenn ein Scope fehlt – das betroffene Tool meldet die Ablehnung, und die anderen funktionieren weiter. Führen Sie toast_check_connection aus, um genau zu sehen, was gewährt ist.

Sie benötigen außerdem Ihre Restaurant-GUID. toast_check_connection meldet sie, oder Sie finden sie in der Toast-Web-URL, wenn der Standort ausgewählt ist, oder verwenden Sie toast_list_restaurants mit einer Management-Gruppen-GUID.

Installation

npm install && npm run build

Kopieren Sie dann die Umgebungsvorlage und füllen Sie sie aus:

cp .env.example .env

Setzen Sie mindestens TOAST_CLIENT_ID, TOAST_CLIENT_SECRET und TOAST_RESTAURANT_GUID. Der Server liest diese Datei automatisch (über die native Env-Datei-Unterstützung von Node), und .env ist in .gitignore aufgeführt.

Überprüfen Sie die Anmeldedaten, bevor Sie etwas anschließen:

npm run check-connection

Das gibt die Umgebung, die gewährten Berechtigungen, den Restaurantnamen, seine Zeitzone und Abschlussstunde sowie das aktuelle Geschäftsdatum aus.

Verbinden Sie es mit Claude

Der Server spricht MCP über stdio. Sie haben zwei Optionen für Anmeldedaten, und Sie benötigen nur eine:

• Lassen Sie sie in .env. Der Server lädt .env aus seinem eigenen Paketverzeichnis, unabhängig davon, aus welchem Arbeitsverzeichnis der Client ihn startet, sodass die folgende Konfiguration ohne env-Block funktioniert – und Ihre Geheimnisse bleiben aus der Konfigurationsdatei des Clients heraus.

• Setzen Sie sie in den env-Block des Clients, wie unten gezeigt. Echte Umgebungsvariablen haben immer Vorrang vor .env, also gewinnt diese, wenn beide vorhanden sind.

Claude Code

Wenn Sie .env ausgefüllt haben, ist das alles, was Sie brauchen – keine Anmeldedaten im Befehl:

claude mcp add toast -- node /absolute/path/to/toast_mcp/dist/index.js

Um Anmeldedaten stattdessen explizit zu übergeben:

claude mcp add toast --env TOAST_CLIENT_ID=your-id --env TOAST_CLIENT_SECRET=your-secret --env TOAST_RESTAURANT_GUID=your-restaurant-guid -- node /absolute/path/to/toast_mcp/dist/index.js

Claude Desktop

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "toast": {
      "command": "node",
      "args": ["/absolute/path/to/toast_mcp/dist/index.js"],
      "env": {
        "TOAST_CLIENT_ID": "your-client-id",
        "TOAST_CLIENT_SECRET": "your-client-secret",
        "TOAST_RESTAURANT_GUID": "your-restaurant-guid"
      }
    }
  }
}

Lassen Sie den env-Block vollständig weg, wenn Sie .env verwenden. Verwenden Sie unter Windows Schrägstriche oder maskierte Backslashes im Pfad.

Konfiguration

Tools

Verbindung und Einrichtung

Berichte

Nachschlagen

Datumsangaben

Jeder Bericht arbeitet mit Geschäftsdaten in der eigenen Zeitzone des Restaurants und berücksichtigt die konfigurierte Abschlussstunde – so fällt ein Verkauf am Samstag um 2 Uhr morgens auf das Geschäftsdatum von Freitag, genau wie in Toasts eigenen Berichten.

Verwenden Sie date_range für eine Voreinstellung (today, yesterday, this_week, last_week, last_7_days, last_14_days, last_30_days, last_90_days, this_month, last_month, month_to_date, year_to_date) oder start_date / end_date für alles andere. Diese akzeptieren 2026-08-01, 20260801, today, yesterday oder relative Offsets wie -7d, -2w, -3m. Der Standard, wenn nichts angegeben ist, ist gestern.

Wie die Zahlen definiert sind

Diese stammen aus rohen Bestelldaten und können daher geringfügig von den Berichten in Toast Web abweichen, die zusätzliche Buchhaltungsregeln anwenden. Jeder Bericht wiederholt seine Definitionen in seiner Ausgabe.

Eine Feinheit, die man kennen sollte. Im Datenmodell von Toast enthalten die price und preDiscountPrice eines Positionsartikels bereits die Preise seiner verschachtelten Modifikatoren. Wenn man Modifikatoren zusätzlich zu ihrem übergeordneten Element summiert, werden alle Aufpreise doppelt gezählt. Dieser Server summiert immer nur Auswahlmöglichkeiten auf oberster Ebene, und die Testsuite stellt sicher, dass der Modifikator nicht doppelt gezählt wird.

Zwei Annahmen werden überall dort angegeben, wo sie gelten: Arbeitskosten schätzen Überstunden mit 1,5× dem aufgezeichneten Stundenlohn (Toast meldet den tatsächlichen Überstundensatz nicht; der Multiplikator ist ein Tool-Argument), und Zeiteinträge ohne aufgezeichneten Lohn tragen Stunden, aber keine Kosten bei.

Ratenbegrenzungen und Caching

Toast erlaubt insgesamt 20 Anfragen pro Sekunde, 5 pro Sekunde für ordersBulk und 1 pro Sekunde für menus. Der Server verwendet einen Token-Bucket-Limiter unterhalb dieser Obergrenzen und wiederholt 429- und 5xx-Antworten mit exponentiellem Backoff, wobei Retry-After berücksichtigt wird.

Da ein Monatsbericht bedeutet, jede Bestellung für 30 Geschäftstage abzurufen, werden abgeschlossene Daten als JSON auf der Festplatte zwischengespeichert. Heute und die vorherigen TOAST_CACHE_SETTLE_DAYS Tage (standardmäßig 1) werden immer neu abgerufen, da sich Trinkgelder, Rückerstattungen und Abschlüsse ständig ändern. Übergeben Sie refresh: true an einen beliebigen Bericht, um den Cache zu umgehen, oder führen Sie toast_clear_cache aus, nachdem in Toast eine Korrektur für ein älteres Datum vorgenommen wurde. Jede Berichtsfußzeile gibt an, wie viele Daten aus dem Cache stammen und wie viele live.

Entwicklung

npm run typecheck    # type-check without emitting
npm run build        # compile to dist/
npm test             # build, then run the end-to-end smoke test

npm test startet eine simulierte Toast-API mit manuell berechneten Fixture-Daten, startet den kompilierten Server als echten Kindprozess und steuert alle 19 Tools über stdio, wie es ein MCP-Client tun würde. Es prüft die tatsächliche Arithmetik (Nettoumsatz, Steuern, Trinkgelder, aufgeschobene Einnahmen, Arbeitskosten, Stornosummen), dass GUIDs in Namen aufgelöst werden, dass Paginierung nicht abschneidet, dass der Cache korrekt verwendet und umgangen wird, dass Fehler lesbar erscheinen – und dass außer GET-Anfragen und dem Auth-POST nichts die API erreicht.

Aufbau

src/
  index.ts        MCP server entry, tool registration, --check-connection
  env.ts          .env discovery and loading, with environment taking precedence
  config.ts       Environment loading and validation
  auth.ts         Token acquisition, caching, refresh (the only POST)
  client.ts       Read-only HTTP client: retries, rate limiting, pagination
  rateLimiter.ts  Token-bucket limiters matched to Toast's documented limits
  cache.ts        On-disk cache for settled business dates
  service.ts      Data access across Orders, Config, Menus, Labor, Cash, Stock
  dates.ts        Business-date arithmetic in the restaurant's time zone
  aggregate.ts    Revenue definitions and the single-pass fact builder
  grouping.ts     Group-by dimensions
  names.ts        GUID to human name resolution
  money.ts        Integer-cent arithmetic and currency formatting
  format.ts       Text table rendering
  tools/          One module per tool group
test/
  mock-toast.mjs  Fixture Toast API
  config.mjs      Credential loading, .env precedence, error messages
  smoke.mjs       End-to-end assertions

Fehlerbehebung

„Fehlende erforderliche Umgebungsvariable(n)" – der Server hat keine Anmeldedaten gefunden. Die Meldung nennt den genauen .env-Pfad, der erstellt werden muss. Wenn sie sagt, dass eine .env gelesen wurde, aber die Variable nicht definiert ist, prüfen Sie auf Tippfehler oder einen leeren Wert – ein leerer Wert gilt als nicht gesetzt.

Ein .env-Wert scheint ignoriert zu werden – etwas in der echten Umgebung überschreibt ihn, da Umgebungsvariablen Vorrang haben. toast_check_connection meldet, aus welcher Quelle die Anmeldedaten stammen. (Eine als leer exportierte Variable, z. B. TOAST_CLIENT_ID=, wird als nicht gesetzt behandelt und blockiert den .env-Wert nicht.)

403 bei einigen Tools, aber nicht bei anderen – eine fehlende Berechtigung. Führen Sie toast_check_connection aus; die API-Zugriffstabelle zeigt, welche verweigert werden. Fügen Sie den Bereich zu Ihrem Anmeldedatensatz in Toast Web hinzu.

Server oder Kategorien erscheinen als #a1b2c3d4 – der Konfigurations- oder Arbeitsbereich ist nicht gewährt, daher können GUIDs nicht in Namen aufgelöst werden. Die Verkaufszahlen sind dennoch korrekt.

Zahlen weichen leicht von Toast Web ab – erwartet; siehe die Definitionstabelle oben. Die häufigsten Ursachen sind, dass das Dashboard von Toast Servicegebühren oder aufgeschobene Einnahmen anders behandelt.

Ein vergangenes Datum wirkt veraltet – eine Korrektur wurde in Toast vorgenommen, nachdem das Datum zwischengespeichert wurde. Übergeben Sie refresh: true oder führen Sie toast_clear_cache aus.

Berichte sind beim ersten Mal langsam – ein 90-Tage-Bericht ruft jede Bestellung für 90 Geschäftstage ab. Der zweite Lauf wird aus dem Cache bedient.