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

order-dashboard - Real-time order monitoring
order-detail - Detailed order view
order-grid - Searchable order grid
menu-manager - Menu management interface
menu-item-detail - Item detail view
employee-dashboard - Employee management
employee-schedule - Schedule planning
labor-dashboard - Labor analytics
restaurant-overview - Restaurant config
table-map - Interactive floor plan
payment-history - Payment tracking
inventory-tracker - Inventory management
customer-detail - Customer profiles
customer-loyalty - Loyalty program
sales-dashboard - Sales analytics
menu-performance - Menu analytics
tip-summary - Tip tracking
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

Log in to Toast Web Admin
Navigate to Integrations → API
Create a new API token
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

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
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