mcpengine/servers/toast/README.md

Toast MCP Server

A complete Model Context Protocol (MCP) server for Toast POS integration, providing comprehensive access to orders, menus, employees, labor, payments, inventory, customers, and reporting.

Features

🔧 50+ MCP Tools

Orders (9 tools)

• toast_list_orders - List orders with date range filtering
• toast_get_order - Get order details
• toast_create_order - Create new orders
• toast_update_order - Update order details
• toast_add_order_item - Add items to orders
• toast_remove_order_item - Remove items from orders
• toast_apply_discount - Apply discounts
• toast_void_order - Void orders
• toast_list_order_checks - List order checks

Menus (8 tools)

• toast_list_menus - List all menus
• toast_get_menu - Get menu details
• toast_list_menu_groups - List menu groups
• toast_get_menu_group - Get group details
• toast_list_menu_items - List menu items
• toast_get_menu_item - Get item details
• toast_list_item_modifiers - List item modifiers
• toast_update_item_price - Update item pricing

Employees (10 tools)

• toast_list_employees - List all employees
• toast_get_employee - Get employee details
• toast_create_employee - Create new employees
• toast_update_employee - Update employee info
• toast_delete_employee - Delete employees
• toast_list_employee_jobs - List employee jobs
• toast_list_employee_shifts - List employee shifts
• toast_clock_in - Clock in employees
• toast_clock_out - Clock out employees
• toast_list_time_entries - List time entries

Labor (5 tools)

• toast_list_shifts - List all shifts
• toast_get_shift - Get shift details
• toast_list_shift_breaks - List shift breaks
• toast_get_labor_cost - Get labor cost reports
• toast_list_jobs - List job positions

Restaurant (5 tools)

• toast_get_restaurant_info - Get restaurant info
• toast_list_revenue_centers - List revenue centers
• toast_list_dining_options - List dining options
• toast_list_service_areas - List service areas
• toast_list_tables - List tables

Payments (5 tools)

• toast_list_payments - List payments
• toast_get_payment - Get payment details
• toast_void_payment - Void payments
• toast_refund_payment - Process refunds
• toast_list_tips - List tips

Inventory (5 tools)

• toast_list_inventory_items - List inventory
• toast_get_inventory_item - Get item details
• toast_update_inventory_count - Update counts
• toast_list_vendors - List vendors
• toast_create_purchase_order - Create POs

Customers (6 tools)

• toast_list_customers - List customers
• toast_get_customer - Get customer details
• toast_create_customer - Create customers
• toast_update_customer - Update customer info
• toast_list_customer_loyalty - List loyalty info
• toast_add_loyalty_points - Add loyalty points

Reporting (5 tools)

• toast_sales_summary - Sales summary reports
• toast_labor_cost_report - Labor cost analysis
• toast_menu_item_performance - Menu performance
• toast_revenue_by_hour - Hourly revenue
• toast_tip_summary - Tip summaries

Cash Management (2 tools)

• toast_list_cash_entries - List cash entries
• toast_get_drawer_status - Get drawer status

📊 18 MCP Apps

1. order-dashboard - Real-time order monitoring
2. order-detail - Detailed order view
3. order-grid - Searchable order grid
4. menu-manager - Menu management interface
5. menu-item-detail - Item detail view
6. employee-dashboard - Employee management
7. employee-schedule - Schedule planning
8. labor-dashboard - Labor analytics
9. restaurant-overview - Restaurant config
10. table-map - Interactive floor plan
11. payment-history - Payment tracking
12. inventory-tracker - Inventory management
13. customer-detail - Customer profiles
14. customer-loyalty - Loyalty program
15. sales-dashboard - Sales analytics
16. menu-performance - Menu analytics
17. tip-summary - Tip tracking
18. revenue-by-hour - Hourly revenue analysis

Installation

npm install
npm run build

Configuration

Set the following environment variables:

export TOAST_API_TOKEN="your-toast-api-token"
export TOAST_RESTAURANT_GUID="your-restaurant-guid"
export TOAST_BASE_URL="https://ws-api.toasttab.com"  # Optional, defaults to production

Getting Toast API Credentials

1. Log in to Toast Web Admin
2. Navigate to Integrations → API
3. Create a new API token
4. Copy your Restaurant GUID from Settings → Restaurant Info

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "toast": {
      "command": "node",
      "args": ["/path/to/toast/dist/main.js"],
      "env": {
        "TOAST_API_TOKEN": "your-token",
        "TOAST_RESTAURANT_GUID": "your-guid"
      }
    }
  }
}

Direct Execution

npm start

API Client Features

• ✅ Bearer token authentication
• ✅ Restaurant GUID injection
• ✅ Automatic pagination handling
• ✅ Comprehensive error handling
• ✅ Rate limit awareness
• ✅ Retry logic
• ✅ Request/response logging

Tool Examples

List Today's Orders

{
  "name": "toast_list_orders",
  "arguments": {
    "startDate": "2025-01-28T00:00:00Z",
    "endDate": "2025-01-28T23:59:59Z"
  }
}

Create New Order

{
  "name": "toast_create_order",
  "arguments": {
    "diningOptionGuid": "abc-123",
    "tableGuid": "table-5",
    "numberOfGuests": 4
  }
}

Add Item to Order

{
  "name": "toast_add_order_item",
  "arguments": {
    "orderId": "order-123",
    "checkGuid": "check-456",
    "itemGuid": "item-789",
    "quantity": 2,
    "modifiers": [
      { "guid": "mod-1", "quantity": 1 }
    ]
  }
}

Clock In Employee

{
  "name": "toast_clock_in",
  "arguments": {
    "employeeGuid": "emp-123",
    "jobGuid": "job-server"
  }
}

Get Sales Summary

{
  "name": "toast_sales_summary",
  "arguments": {
    "startDate": "2025-01-28T00:00:00Z",
    "endDate": "2025-01-28T23:59:59Z"
  }
}

MCP App Access

Access apps via MCP resources:

toast://apps/order-dashboard
toast://apps/sales-dashboard
toast://apps/menu-manager
toast://apps/employee-schedule
toast://apps/table-map

Architecture

toast/
├── src/
│   ├── api-client.ts           # Toast API client with auth & pagination
│   ├── server.ts               # MCP server implementation
│   ├── main.ts                 # Entry point
│   ├── types/
│   │   └── index.ts            # TypeScript type definitions
│   ├── tools/
│   │   ├── orders-tools.ts     # Order management tools
│   │   ├── menus-tools.ts      # Menu management tools
│   │   ├── employees-tools.ts  # Employee management tools
│   │   ├── labor-tools.ts      # Labor tracking tools
│   │   ├── restaurant-tools.ts # Restaurant config tools
│   │   ├── payments-tools.ts   # Payment processing tools
│   │   ├── inventory-tools.ts  # Inventory management tools
│   │   ├── customers-tools.ts  # Customer management tools
│   │   ├── reporting-tools.ts  # Reporting & analytics tools
│   │   └── cash-tools.ts       # Cash management tools
│   └── apps/
│       └── index.ts            # MCP app definitions
├── package.json
├── tsconfig.json
└── README.md

Error Handling

All tools return structured error responses:

{
  "content": [{
    "type": "text",
    "text": "Error: Order not found (404)"
  }],
  "isError": true
}

Pagination

Tools support automatic pagination:

{
  "name": "toast_list_orders",
  "arguments": {
    "page": 2,
    "pageSize": 50
  }
}

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Start server
npm start

API Documentation

Toast API documentation: https://doc.toasttab.com/

Key Endpoints

• Orders: /orders/v2/orders
• Menus: /menus/v2/menus
• Labor: /labor/v1/employees
• Payments: /payments/v1/payments
• Restaurant: /restaurants/v1/restaurants

Security

• API tokens stored in environment variables
• No credentials in code or logs
• Bearer token authentication
• HTTPS-only communication
• Restaurant GUID scoping

Support

For Toast API support: https://central.toasttab.com/s/support

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Roadmap

• WebSocket support for real-time updates
• Advanced reporting with custom date ranges
• Menu optimization recommendations
• Labor cost forecasting
• Inventory auto-reordering
• Customer segmentation
• A/B testing for menu items
• Integration with third-party delivery platforms
• Multi-location support
• Advanced analytics dashboards

Version History

1.0.0 (2025-01-28)

• Initial release
• 50+ MCP tools
• 18 MCP apps
• Complete Toast API integration
• Comprehensive type definitions
• Error handling and pagination