jake/toast-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Customize: Platform-specific README, tools, and docs

Browse Source
This commit is contained in:
Jake Shore 2026-02-02 06:57:03 -05:00
parent a42d750e8e
commit 31a22d7350
3 changed files with 122 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.env.example
View File

@ -1,2 +1,5 @@
# Toast API Credentials
TOAST_API_KEY=your-api-key-here
# Get these from: https://dev.toasttab.com/
TOAST_CLIENT_ID=your-client-id-here
TOAST_CLIENT_SECRET=your-client-secret-here
TOAST_RESTAURANT_GUID=your-restaurant-guid-here

181
README.md
View File

@ -4,38 +4,46 @@
---
# 🚀 Toast MCP Server — 2026 Complete Version
# 🍞 Toast MCP Server — Restaurant Operations on Autopilot
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Toast workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**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-Native Power Moves
### 🎯 Toast-Specific Power Moves
The AI can directly control your Toast account with natural language:
| 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` |
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Toast data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Toast with other tools seamlessly
### 🔗 The Real Power: Natural Language Restaurant Ops
### 🔗 The Real Power: Combining Tools
Instead of clicking through Toast dashboards:
AI can chain multiple Toast operations together:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- *"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
**93 API tools** covering the entire Toast platform (Restaurant & POS).
**8 restaurant-focused API tools** covering Toast's core POS functionality:
All with proper error handling, automatic authentication, and TypeScript types.
- **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 (Local)
### Option 1: Claude Desktop (Recommended)
1. **Clone and build:**
```bash
@ -45,82 +53,115 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Toast API credentials** (see Authentication section below)
2. **Get your Toast API credentials:**
- Log into [Toast Developer Portal](https://dev.toasttab.com/)
- Create a new integration (Restaurant Management API)
- Save your **Client ID**, **Client Secret**, and **Restaurant GUID**
3. **Configure Claude Desktop:**
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"toast": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/toast-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/toast-mcp-2026-complete/dist/index.js"],
"env": {
"TOAST_API_KEY": "your-api-key-here"
"TOAST_CLIENT_ID": "your-client-id",
"TOAST_CLIENT_SECRET": "your-client-secret",
"TOAST_RESTAURANT_GUID": "your-restaurant-guid"
}
}
}
}
```
4. **Restart Claude Desktop**
4. **Restart Claude Desktop** — you'll see 8 Toast tools appear in the MCP section
### Option 2: Deploy to Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/toast-mcp)
1. Click the button above
2. Set your Toast API credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
### Option 2: Local Development
```bash
docker build -t toast-mcp .
docker run -p 3000:3000 \
-e TOAST_API_KEY=your-key \
toast-mcp
cp .env.example .env
# Edit .env with your Toast credentials
npm run dev
```
## 🔐 Authentication
See the official [Toast API documentation](https://docs.toast.com) for authentication details.
Toast uses **OAuth2 Client Credentials** flow:
The MCP server handles token refresh automatically.
1. Go to [Toast Developer Portal](https://dev.toasttab.com/)
2. Navigate to **Integrations** → **Create Integration**
3. Select **Restaurant Management API** scope
4. Copy your **Client ID** and **Client Secret**
5. 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](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, you can use natural language. Examples:
Once connected to Claude:
- *"Show me recent activity in Toast"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
**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
- Toast account with API access (paid plan required)
### Setup
### Local Setup
```bash
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 Toast credentials
# 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
```bash
@ -131,31 +172,41 @@ npm run test:coverage # Coverage report
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "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 config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- 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
- [Toast API Documentation](https://docs.toast.com)
- [Toast API Documentation](https://doc.toasttab.com/doc/devguide/apiOverview.html)
- [Toast Developer Portal](https://dev.toasttab.com/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- [Claude Desktop Setup](https://claude.ai/desktop)
## 🤝 Contributing
Contributions are welcome! Please:
Contributions welcome! To add new Toast API endpoints:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request
2. Add tool definitions to `src/index.ts` (tools array)
3. Implement handlers in `handleTool()` function
4. Update README with new capabilities
5. Submit a PR
## 📄 License
@ -163,10 +214,10 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
**Want more MCP servers?** Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms (Gusto, Calendly, Stripe, QuickBooks, and more).
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

4
package.json
View File

@ -1,10 +1,10 @@
{
"name": "toast-mcp-server",
"version": "1.0.0",
"description": "MCP server for Toast API - 2026 Complete Version",
"description": "MCP server for Toast POS - Restaurant operations with 8 AI-ready tools",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",