Toast MCP Server

Сервер Model Context Protocol только для чтения для API Toast POS. Он позволяет ИИ-ассистенту отвечать на вопросы о вашем ресторане и формировать отчёты по продажам, трудозатратам и кассе непосредственно из живых данных Toast.

Он никогда не записывает данные в Toast. HTTP-клиент выполняет только GET-запросы; единственный POST в кодовой базе — это вызов аутентификации, который Toast требует для выпуска токена, и он изолирован в src/auth.ts. Смоук-тест это подтверждает.

О чём можно спросить

После подключения работают такие вопросы:

• «Как у нас прошла прошлая неделя по сравнению с предыдущей?»

• «Какие были наши топ-20 позиций по чистым продажам в июле, и какова средняя цена каждой?»

• «Разбей продажи по часам за прошлую субботу — когда у нас настоящий вечерний час пик?»

• «Каково соотношение наличных и карт в этом месяце, и сколько мы заплатили комиссий за обработку карт?»

• «Какие скидки используются чаще всего, и насколько?»

• «Покажи все аннулирования за последние две недели с причиной и кто работал.»

• «Какой процент от чистых продаж составили трудозатраты в прошлом месяце, по сотрудникам?»

• «Что у нас сейчас 86-е (нет в наличии)?»

• «Найди заказ на $340 с пятничного вечера и покажи, что в него входило.»

• «Каковы наши часы работы по воскресеньям, и какие варианты обслуживания у нас настроены?»

Related MCP server: Shopify MCP Server

Требования

• Node.js 20 или новее (собрано и протестировано на Node 22).

• Учётные данные Toast API. Для ресторана, который отчитывается по собственным данным, подходящий продукт — Standard API Access, который по своей конструкции доступен только для чтения и настраивается самостоятельно:

  1. В Toast Web перейдите в Integrations → Toast API access → Manage credentials.

  2. Создайте набор учётных данных, дайте ему имя (например, mcp-reporting) и выберите области чтения, указанные ниже.

  3. Скопируйте client ID и client secret — секрет показывается только один раз.

  Если в вашем аккаунте нет такого варианта, он входит в Restaurant Management Essentials; ваш представитель Toast может его включить. Партнёрские интеграции получают учётные данные от команды интеграций Toast вместо этого.

Области для включения

Для базовой отчётности по продажам нужны только orders:read, config:read и restaurants:read. Сервер корректно деградирует, если область отсутствует — затронутый инструмент сообщает об отказе, а остальные продолжают работать. Запустите toast_check_connection, чтобы увидеть, что именно предоставлено.

Вам также понадобится GUID ресторана. toast_check_connection сообщает его, или найдите его в URL Toast Web при выбранном заведении, или используйте toast_list_restaurants с GUID группы управления.

Установка

npm install && npm run build

Затем скопируйте шаблон окружения и заполните его:

cp .env.example .env

Как минимум задайте TOAST_CLIENT_ID, TOAST_CLIENT_SECRET и TOAST_RESTAURANT_GUID. Сервер читает этот файл автоматически (через встроенную поддержку env-файлов Node), а .env игнорируется git.

Проверьте учётные данные перед подключением чего-либо:

npm run check-connection

Это выводит окружение, предоставленные области, название ресторана, его часовой пояс и час закрытия, а также текущую бизнес-дату.

Подключение к Claude

Сервер общается по MCP через stdio. У вас есть два варианта для учётных данных, и нужен только один:

• Оставить их в .env. Сервер загружает .env из собственного каталога пакета независимо от того, из какой рабочей директории клиент его запускает, поэтому приведённая ниже конфигурация работает вообще без блока env — и ваши секреты не попадают в конфигурационный файл клиента.

• Поместить их в блок env клиента, как показано ниже. Настоящие переменные окружения всегда имеют приоритет над .env, поэтому при наличии обоих побеждают они.

Claude Code

Если вы заполнили .env, этого достаточно — никаких учётных данных в команде:

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

Чтобы передать учётные данные явно:

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

Добавьте в claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

Удалите блок env полностью, если используете .env. В Windows используйте прямые слэши или экранированные обратные слэши в пути.

Конфигурация

Инструменты

Подключение и настройка

Отчётность

Поиск

Даты

Каждый отчёт работает с бизнес-датами в часовом поясе ресторана, учитывая настроенный час закрытия — так, продажа в субботу в 2 часа ночи попадает на бизнес-дату пятницы, точно так же, как в собственных отчётах Toast.

Используйте date_range для предустановки (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) или start_date / end_date для любых других. Они принимают 2026-08-01, 20260801, today, yesterday или относительные смещения, например -7d, -2w, -3m. По умолчанию, если ничего не указано, используется вчера.

Как определяются числа

Они берутся из необработанных данных заказов, поэтому могут незначительно отличаться от собственных отчётов Toast Web, которые добавляют дополнительные правила бухгалтерского учёта. Каждый отчёт повторяет свои определения в выводе.

Одна тонкость, которую стоит знать. В модели данных Toast price и preDiscountPrice позиции уже включают цены вложенных модификаторов. Суммирование модификаторов поверх родительской позиции приводит к двойному учёту каждой наценки. Этот сервер всегда суммирует только выборы верхнего уровня, и тестовый набор проверяет, что модификатор не учитывается дважды.

Два допущения указаны там, где они применимы: оценка затрат на труд учитывает сверхурочные по ставке 1.5× от почасовой оплаты, указанной в записи (Toast не сообщает фактическую ставку сверхурочных; множитель является аргументом инструмента), а записи времени без указанной оплаты учитывают часы, но не стоимость.

Ограничения скорости и кэширование

Toast допускает 20 запросов в секунду в целом, 5 в секунду для ordersBulk и 1 в секунду для menus. Сервер использует ограничитель на основе токенов ниже каждого из этих пределов и повторяет запросы с кодами 429 и 5xx с экспоненциальной задержкой, учитывая Retry-After.

Поскольку месячный отчёт означает получение каждого заказа за 30 рабочих дат, завершённые даты кэшируются на диск в формате JSON. Сегодняшняя дата и предыдущие TOAST_CACHE_SETTLE_DAYS дней (по умолчанию 1) всегда запрашиваются заново, так как чаевые, возвраты и закрытия смен продолжают меняться. Передайте refresh: true в любой отчёт, чтобы обойти кэш, или выполните toast_clear_cache после внесения исправления в Toast для более ранней даты. В нижнем колонтитуле каждого отчёта указано, сколько дат взято из кэша, а сколько — в реальном времени.

Разработка

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 запускает имитацию Toast API с вручную рассчитанными тестовыми данными, запускает скомпилированный сервер как реальный дочерний процесс и управляет всеми 19 инструментами через stdio, как это делал бы MCP-клиент. Он проверяет фактические вычисления (чистые продажи, налог, чаевые, отложенная выручка, затраты на труд, суммы аннулирований), что GUID преобразуются в имена, что пагинация не обрезает данные, что кэш используется и обходится правильно, что ошибки отображаются читаемо — и что к API поступают только GET-запросы и аутентификационный POST.

Структура

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

Устранение неполадок

«Отсутствуют обязательные переменные окружения» — сервер не нашёл учётные данные. В сообщении указан точный путь к файлу .env, который нужно создать. Если сказано, что .env был прочитан, но переменная не определена, проверьте опечатку или пустое значение — пустое значение считается неустановленным.

Значение из .env игнорируется — что-то в реальном окружении переопределяет его, поскольку переменные окружения имеют приоритет. toast_check_connection сообщает, из какого источника получены учётные данные. (Переменная, экспортированная как пустая, например TOAST_CLIENT_ID=, считается неустановленной и не блокирует значение из .env.)

403 на некоторых инструментах, но не на других — отсутствует область доступа. Запустите toast_check_connection; таблица доступа к API показывает, какие области запрещены. Добавьте область в набор учётных данных в Toast Web.

Серверы или категории отображаются как #a1b2c3d4 — не предоставлена область Configuration или Labor, поэтому GUID не могут быть преобразованы в имена. Показатели продаж при этом остаются корректными.

Числа немного отличаются от Toast Web — это ожидаемо; см. таблицу определений выше. Наиболее частые причины — панель Toast иначе обрабатывает сервисные сборы или отложенную выручку.

Прошедшая дата выглядит устаревшей — в Toast было внесено исправление после того, как дата была закэширована. Передайте refresh: true или выполните toast_clear_cache.

Отчёты выполняются медленно при первом запуске — отчёт за 90 дней получает каждый заказ за 90 рабочих дат. Второй запуск обслуживается из кэша.