jake/toast-mcp-2026-complete

Jake Shore 31a22d7350 Customize: Platform-specific README, tools, and docs

2026-02-02 06:57:03 -05:00

7.0 KiB

Raw Permalink Blame History

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

🍞 Toast MCP Server — Restaurant Operations on Autopilot

💡 What This Unlocks

This MCP server gives AI direct access to your Toast POS system. Stop manually pulling reports, updating menu items, or tracking labor costs. Just tell Claude what you need, and it happens.

🎯 Toast-Specific Power Moves

Use Case	What It Does	Tools Used
"86" items instantly	Mark menu items out of stock across all terminals	`list_menu_items`, `update_menu_item`
Daily sales reconciliation	Pull all orders + payments for a business day	`list_orders`, `get_order`, `list_checks`
Labor cost analysis	Compare actual hours worked vs. scheduled shifts	`list_employees`, `get_labor`
Order investigation	Find specific orders by time/amount, void if needed	`list_orders`, `get_order`, `void_check`
Menu sync verification	Audit menu items against your master menu list	`list_menu_items`

🔗 The Real Power: Natural Language Restaurant Ops

Instead of clicking through Toast dashboards:

"Show me all orders from last night's dinner rush (5-9pm)"
"Mark the grilled salmon as 86'd"
"What's our total labor cost for this week?"
"Find the order with the $127 total from yesterday"
"Void check #4521 — customer never showed up"

📦 What's Inside

8 restaurant-focused API tools covering Toast's core POS functionality:

Orders: list_orders, get_order — Sales data, items, modifiers, payments
Checks: list_checks, void_check — Tab management and corrections
Menu: list_menu_items, update_menu_item — Inventory & 86'd items
Labor: list_employees, get_labor — Staff scheduling & time tracking

All with automatic OAuth2 authentication, proper error handling, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Recommended)

Clone and build:

git clone https://github.com/BusyBee3333/Toast-MCP-2026-Complete.git
cd toast-mcp-2026-complete
npm install
npm run build

Get your Toast API credentials:
- Log into Toast Developer Portal
- Create a new integration (Restaurant Management API)
- Save your Client ID, Client Secret, and Restaurant GUID

Configure Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "toast": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/toast-mcp-2026-complete/dist/index.js"],
      "env": {
        "TOAST_CLIENT_ID": "your-client-id",
        "TOAST_CLIENT_SECRET": "your-client-secret",
        "TOAST_RESTAURANT_GUID": "your-restaurant-guid"
      }
    }
  }
}

Restart Claude Desktop — you'll see 8 Toast tools appear in the MCP section

Option 2: Local Development

cp .env.example .env
# Edit .env with your Toast credentials
npm run dev

🔐 Authentication

Toast uses OAuth2 Client Credentials flow:

Go to Toast Developer Portal
Navigate to Integrations → Create Integration
Select Restaurant Management API scope
Copy your Client ID and Client Secret
Find your Restaurant GUID in Toast Web (Settings → Restaurant Info)

Required Scopes:

Orders (read)
Menus (read/write)
Labor (read)

API Docs: https://doc.toasttab.com/doc/devguide/apiOverview.html

The MCP server automatically handles token refresh (tokens expire after 1 hour).

🎯 Example Prompts

Once connected to Claude:

Sales & Orders:

"Pull all orders from yesterday between 6-9pm"
"Show me order abc123 with full details"
"What were our top-selling items last week?"

Menu Management:

"List all menu items with prices"
"Mark the ribeye steak as out of stock"
"What items are currently 86'd?"

Labor & Staffing:

"Show me all employees"
"Get labor data for last Monday-Friday"
"Calculate total hours worked by employee X"

Check Operations:

"List all open checks right now"
"Void check #4521 with reason 'customer no-show'"

🛠️ Development

Prerequisites

Node.js 18+
npm or yarn
Toast account with API access (paid plan required)

Local Setup

git clone https://github.com/BusyBee3333/Toast-MCP-2026-Complete.git
cd toast-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your credentials
npm run build
npm start

Project Structure

toast-mcp-2026-complete/
├── src/
│   └── index.ts          # Main MCP server + Toast API client
├── dist/                 # Compiled JavaScript (npm run build)
├── package.json
├── tsconfig.json
└── .env.example

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

🐛 Troubleshooting

"Toast auth error: 401"

Verify your Client ID and Client Secret are correct
Check that your integration has the required scopes enabled
Ensure your Restaurant GUID matches your actual restaurant

"Toast API error: 403 Forbidden"

Your API credentials don't have the necessary permissions
Check your integration's scope settings in the Toast Developer Portal

"Tools not appearing in Claude"

Restart Claude Desktop after updating claude_desktop_config.json
Verify the path is absolute (no ~ or relative paths)
Check that npm run build completed successfully
Look for the dist/index.js file

"Toast-Restaurant-External-ID header required"

Make sure TOAST_RESTAURANT_GUID is set in your environment
This is different from your Client ID — find it in Toast Web settings

📖 Resources

🤝 Contributing

Contributions welcome! To add new Toast API endpoints:

Fork the repo
Add tool definitions to src/index.ts (tools array)
Implement handlers in handleTool() function
Update README with new capabilities
Submit a PR

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms (Gusto, Calendly, Stripe, QuickBooks, and more).

Questions? Open an issue or join our Discord community.

7.0 KiB Raw Permalink Blame History