Servidor Toast MCP

Un servidor de solo lectura del Model Context Protocol para la API de Toast POS. Permite que un asistente de IA responda preguntas sobre tu restaurante y genere informes de ventas, mano de obra y caja directamente desde los datos en vivo de Toast.

Nunca escribe en Toast. El cliente HTTP solo emite solicitudes GET; el único POST en el código es la llamada de autenticación que Toast requiere para generar un token, y está aislado en src/auth.ts. La prueba de humo lo verifica.

Qué puedes preguntar

Una vez conectado, preguntas como estas funcionan:

• "¿Cómo nos fue la semana pasada en comparación con la anterior?"

• "¿Cuáles fueron nuestros 20 artículos principales por ventas netas en julio, y cuál es el precio promedio de cada uno?"

• "Desglosa las ventas por hora para el sábado pasado: ¿cuándo es nuestro verdadero rush de la cena?"

• "¿Cuál es nuestra mezcla de efectivo vs. tarjeta este mes, y cuánto pagamos en comisiones de procesamiento de tarjetas?"

• "¿Qué descuentos se están usando más, y por cuánto?"

• "Muéstrame todos los anulados de las últimas dos semanas con el motivo y quién estaba trabajando."

• "¿Cuál fue la mano de obra como porcentaje de las ventas netas el mes pasado, por empleado?"

• "¿Qué tenemos agotado (86'd) ahora mismo?"

• "Encuentra el pedido de $340 del viernes por la noche y muéstrame qué contenía."

• "¿Cuáles son nuestros horarios los domingos, y qué opciones de servicio tenemos configuradas?"

Related MCP server: Shopify MCP Server

Requisitos

• Node.js 20 o superior (compilado y probado en Node 22).

• Credenciales de la API de Toast. Para un restaurante que informa sobre sus propios datos, el producto adecuado es Acceso API estándar, que es de solo lectura por diseño y autoservicio:

  1. En Toast Web, ve a Integraciones → Acceso a la API de Toast → Administrar credenciales.

  2. Crea un conjunto de credenciales, asígnale un nombre (por ejemplo, mcp-reporting) y selecciona los alcances de lectura a continuación.

  3. Copia el ID de cliente y el secreto de cliente; el secreto se muestra solo una vez.

  Si tu cuenta no tiene esa opción, es parte de Restaurant Management Essentials; tu representante de Toast puede activarla. Las integraciones de socios obtienen credenciales del equipo de integraciones de Toast en su lugar.

Alcances a habilitar

Solo se necesitan orders:read, config:read y restaurants:read para los informes de ventas principales. El servidor se degrada correctamente si falta un alcance: la herramienta afectada informa la denegación y las demás siguen funcionando. Ejecuta toast_check_connection para ver exactamente qué está concedido.

También necesitas tu GUID de restaurante. toast_check_connection lo informa, o búscalo en la URL de Toast Web cuando la ubicación está seleccionada, o usa toast_list_restaurants con un GUID de grupo de gestión.

Instalación

npm install && npm run build

Luego copia la plantilla de entorno y complétala:

cp .env.example .env

Como mínimo, establece TOAST_CLIENT_ID, TOAST_CLIENT_SECRET y TOAST_RESTAURANT_GUID. El servidor lee este archivo automáticamente (mediante el soporte nativo de archivos de entorno de Node), y .env está en gitignore.

Verifica las credenciales antes de conectar cualquier cosa:

npm run check-connection

Eso imprime el entorno, los alcances concedidos, el nombre del restaurante, su zona horaria y hora de cierre, y la fecha comercial actual.

Conéctalo a Claude

El servidor habla MCP sobre stdio. Tienes dos opciones para las credenciales, y solo necesitas una:

• Déjalas en .env. El servidor carga .env desde su propio directorio de paquete, independientemente del directorio de trabajo desde el que el cliente lo inicie, por lo que la configuración a continuación funciona sin ningún bloque env en absoluto, y tus secretos permanecen fuera del archivo de configuración del cliente.

• Ponlas en el bloque env del cliente, como se muestra a continuación. Las variables de entorno reales siempre tienen prioridad sobre .env, por lo que esto gana si ambos están presentes.

Claude Code

Si completaste .env, esto es todo lo que necesitas: sin credenciales en el comando:

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

Para pasar credenciales explícitamente en su lugar:

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

Agrega a 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"
      }
    }
  }
}

Elimina el bloque env por completo si estás usando .env. En Windows usa barras diagonales o barras invertidas escapadas en la ruta.

Configuración

Herramientas

Conexión y configuración

Informes

Búsqueda

Fechas

Cada informe trabaja con fechas comerciales en la zona horaria del restaurante, respetando su hora de cierre configurada, por lo que una venta del sábado a las 2 a.m. cae en la fecha comercial del viernes, exactamente como en los informes de Toast.

Usa date_range para un valor predefinido (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) o start_date / end_date para cualquier otra cosa. Estos aceptan 2026-08-01, 20260801, today, yesterday o desplazamientos relativos como -7d, -2w, -3m. El valor predeterminado cuando no se especifica nada es yesterday.

Cómo se definen los números

Estos provienen de datos de pedidos sin procesar, por lo que pueden diferir en pequeñas cantidades de los informes de Toast Web, que agregan reglas contables adicionales. Cada informe reafirma sus definiciones en su salida.

Una sutileza que vale la pena conocer. En el modelo de datos de Toast, el price y el preDiscountPrice de una línea de pedido ya incluyen los precios de sus modificadores anidados. Sumar los modificadores además de su padre duplica cada recargo. Este servidor solo suma selecciones de nivel superior, y el conjunto de pruebas verifica que el modificador no se cuente dos veces.

Dos supuestos se indican donde corresponda: el costo de mano de obra estima las horas extra a 1,5× el salario por hora registrado (Toast no informa la tarifa real de horas extra; el multiplicador es un argumento de la herramienta), y las entradas de tiempo sin salario registrado contribuyen horas pero no costo.

Límites de velocidad y caché

Toast permite 20 solicitudes/segundo en general, 5/segundo para ordersBulk y 1/segundo para menus. El servidor ejecuta un limitador de token-bucket por debajo de cada uno de esos límites y reintenta las respuestas 429 y 5xx con retroceso exponencial, respetando Retry-After.

Debido a que un informe de un mes implica extraer cada pedido de 30 fechas hábiles, las fechas completadas se almacenan en caché en disco como JSON. Hoy y los TOAST_CACHE_SETTLE_DAYS días anteriores (1 por defecto) siempre se vuelven a obtener, ya que las propinas, los reembolsos y los cierres siguen cambiando. Pase refresh: true a cualquier informe para omitir la caché, o ejecute toast_clear_cache después de hacer una corrección en Toast para una fecha anterior. El pie de página de cada informe indica cuántas fechas provienen de la caché frente a las en vivo.

Desarrollo

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 inicia una API Toast simulada con datos de prueba calculados a mano, lanza el servidor compilado como un proceso hijo real y maneja las 19 herramientas a través de stdio como lo haría un cliente MCP. Verifica la aritmética real (ventas netas, impuestos, propinas, ingresos diferidos, costo de mano de obra, totales de anulaciones), que los GUID se resuelvan a nombres, que la paginación no trunque, que la caché se use y se omita correctamente, que los errores se muestren de forma legible — y que nada más que solicitudes GET más el POST de autenticación llegue a la API.

Estructura

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

Solución de problemas

"Falta(n) variable(s) de entorno requerida(s)" — el servidor no encontró credenciales. El mensaje indica la ruta exacta de .env a crear. Si dice que se leyó un .env pero no definió la variable, verifique si hay un error tipográfico o un valor en blanco: un valor en blanco cuenta como no definido.

Un valor de .env parece ignorarse — algo en el entorno real lo está sobrescribiendo, ya que las variables de entorno tienen prioridad. toast_check_connection informa de qué fuente provienen las credenciales. (Una variable exportada como vacía, p. ej. TOAST_CLIENT_ID=, se trata como no definida y no bloqueará el valor de .env.)

403 en algunas herramientas pero no en otras — falta un alcance. Ejecute toast_check_connection; la tabla de acceso a la API muestra cuáles están denegados. Agregue el alcance a su conjunto de credenciales en Toast Web.

Los servidores o categorías se muestran como #a1b2c3d4 — el alcance de Configuración o Mano de obra no está concedido, por lo que los GUID no se pueden resolver a nombres. Las cifras de ventas siguen siendo correctas.

Los números difieren ligeramente de Toast Web — es de esperar; consulte la tabla de definiciones anterior. Las causas más comunes son que el panel de Toast trate los cargos por servicio o los ingresos diferidos de manera diferente.

Una fecha pasada parece desactualizada — se hizo una corrección en Toast después de que la fecha se almacenara en caché. Pase refresh: true o ejecute toast_clear_cache.

Los informes son lentos la primera vez — un informe de 90 días extrae cada pedido de 90 fechas hábiles. La segunda ejecución se sirve desde la caché.