Toast MCP Server

A read-only Model Context Protocol server for the Toast POS API. It lets an AI assistant answer questions about your restaurant and generate sales, labor, and cash reports directly from live Toast data.

It never writes to Toast. The HTTP client issues GET requests only; the single POST in the codebase is the authentication call Toast requires to mint a token, and it is isolated in src/auth.ts. The smoke test asserts this.

---

What you can ask

Once connected, questions like these work:

• "How did we do last week compared to the week before?"
• "What were our top 20 items by net sales in July, and what's the average price of each?"
• "Break down sales by hour for last Saturday — when is our real dinner rush?"
• "What's our cash vs card mix this month, and how much did we pay in card processing fees?"
• "Which discounts are getting used most, and by how much?"
• "Show me every void over the last two weeks with the reason and who was working."
• "What was labor as a percentage of net sales last month, by employee?"
• "What are we 86'd on right now?"
• "Find the $340 order from Friday night and show me what was on it."
• "What are our hours on Sundays, and what dining options do we have configured?"

---

Requirements

• Node.js 20 or newer (built and tested on Node 22).

• Toast API credentials. For a restaurant reporting on its own data, the right product is Standard API Access, which is read-only by design and self-serve:

  1. In Toast Web, go to Integrations → Toast API access → Manage credentials.
  2. Create a credential set, name it (e.g. mcp-reporting), and select the read scopes below.
  3. Copy the client ID and client secret — the secret is shown only once.

  If your account doesn't have that option, it's part of Restaurant Management Essentials; your Toast rep can enable it. Partner integrations get credentials from the Toast integrations team instead.

Scopes to enable

Scope	Needed for
orders:read	Every sales report — this is the core one
config:read	Dining options, revenue centers, sales categories, discounts, void reasons, tables
restaurants:read	Location profile, time zone, closeout hour, hours of service
labor:read	Time entries, shifts, jobs
labor.employees:read	Employee names (without it, servers show as short GUIDs)
menus:read	Published menu, prices, modifiers
cashmgmt:read	Drawer entries and deposits
stock:read	Out-of-stock / 86'd items

Only orders:read, config:read and restaurants:read are needed for core sales reporting. The server degrades gracefully if a scope is missing — the affected tool reports the denial and the others keep working. Run toast_check_connection to see exactly what's granted.

You also need your restaurant GUID. toast_check_connection reports it, or find it in the Toast Web URL when the location is selected, or use toast_list_restaurants with a management group GUID.

---

Install

npm install && npm run build

Then copy the environment template and fill it in:

cp .env.example .env

At minimum set TOAST_CLIENT_ID, TOAST_CLIENT_SECRET, and TOAST_RESTAURANT_GUID. The server reads this file automatically (via Node's native env-file support), and .env is gitignored.

Verify the credentials before wiring anything up:

npm run check-connection

That prints the environment, the granted scopes, the restaurant name, its time zone and closeout hour, and the current business date.

---

Connect it to Claude

The server speaks MCP over stdio. You have two options for credentials, and you only need one:

• Leave them in .env. The server loads .env from its own package directory regardless of what working directory the client launches it from, so the config below works with no env block at all — and your secrets stay out of the client's config file.
• Put them in the client's env block, as shown below. Real environment variables always take precedence over .env, so this wins if both are present.

Claude Code

If you filled in .env, this is all you need — no credentials in the command:

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

To pass credentials explicitly instead:

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

Add to 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"
      }
    }
  }
}

Drop the env block entirely if you're using .env. On Windows use forward slashes or escaped backslashes in the path.

---

Configuration

Variable	Default	Purpose
TOAST_CLIENT_ID	(required)	API client ID
TOAST_CLIENT_SECRET	(required)	API client secret
TOAST_ENV_FILE	—	Load this file instead of searching for .env; handy for one credential file per location
TOAST_RESTAURANT_GUID	—	Default restaurant; every tool can override it per call
TOAST_MANAGEMENT_GROUP_GUID	—	Enables toast_list_restaurants for multi-location groups
TOAST_ENV	production	production or sandbox
TOAST_HOSTNAME	—	Full base URL; overrides TOAST_ENV
TOAST_CACHE_ENABLED	true	Disk cache for settled business dates
TOAST_CACHE_DIR	~/.toast-mcp/cache	Where cached orders live
TOAST_CACHE_SETTLE_DAYS	1	Days that are always re-fetched live
TOAST_MAX_DAYS	92	Ceiling on business dates per report
TOAST_LOG_LEVEL	info	debug logs every request to stderr

---

Tools

Connection and setup

Tool	What it does
toast_check_connection	Verifies credentials, probes each API, shows scopes, time zone, closeout hour, cache status
toast_get_restaurant	Location profile: address, phone, hours, currency, online ordering and delivery settings
toast_list_restaurants	Every location in a management group, with GUIDs
toast_clear_cache	Drops the local cache (touches nothing in Toast)

Reporting

Tool	What it does
toast_sales_summary	Headline revenue and volume, optionally vs. the prior period or last year
toast_sales_breakdown	Net sales grouped by item, sales category, menu group, hour, day of week, date, server, dining option, source, revenue center, service area, or table
toast_payment_summary	Tender mix, card brands, tips, refunds, processing fees
toast_discount_summary	Discounts and comps by name, with usage counts
toast_void_report	Voided orders, checks and items by reason
toast_labor_summary	Hours, estimated cost, and labor as a percent of net sales
toast_cash_report	Drawer entries and deposits, reconciled against cash payments

Lookup

Tool	What it does
toast_search_orders	Find individual orders by amount, channel, server, or customer/tab text
toast_get_order	One order in full: line items, modifiers, discounts, payments
toast_list_config	Any of 24 configuration collections — the way to discover GUIDs for filters
toast_get_menu	Published menu structure, price list, or one item's modifier detail
toast_get_stock	Current inventory / 86'd items
toast_list_employees	Roster and job list with wages
toast_time_entries	Individual clock-in/out records
toast_list_shifts	Scheduled shifts

Dates

Every report works in business dates in the restaurant's own time zone, honouring its configured closeout hour — so a 2am Saturday sale lands on Friday's business date, exactly as it does in Toast's own reports.

Use date_range for a preset (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) or start_date / end_date for anything else. Those accept 2026-08-01, 20260801, today, yesterday, or relative offsets like -7d, -2w, -3m. The default when nothing is specified is yesterday.

---

How the numbers are defined

These come from raw order data, so they can differ by small amounts from Toast Web's own reports, which layer on additional accounting rules. Every report restates its definitions in its output.

Measure	Definition
Gross sales	Sum of preDiscountPrice on non-voided, non-deferred line items. Excludes tax.
Discounts	All applied discounts, at both item and check level.
Net sales	Sum of line-item price, which is already net of item and check-level discounts. Equals gross minus discounts. Excludes tax, tips, auto-gratuity and service charges.
Service charges	Applied service charges not flagged as gratuity. Reported separately from net sales.
Auto-gratuity	Service charges flagged gratuity.
Tips	tipAmount on payments that actually collected (voided and denied payments are excluded).
Deferred	Gift card sales. Money collected, but not revenue — held out of net sales and shown on its own line.
Voids	Voided and deleted orders, checks and items are excluded from sales entirely and reported in toast_void_report.

One subtlety worth knowing. In Toast's data model, a line item's price and preDiscountPrice already include the prices of its nested modifiers. Summing modifiers on top of their parent double-counts every upcharge. This server only ever sums top-level selections, and the test suite asserts the modifier is not counted twice.

Two assumptions are stated wherever they apply: labor cost estimates overtime at 1.5× the hourly wage on record (Toast does not report the actual overtime rate; the multiplier is a tool argument), and time entries with no wage on record contribute hours but no cost.

---

Rate limits and caching

Toast allows 20 requests/second overall, 5/second for ordersBulk, and 1/second for menus. The server runs a token-bucket limiter below each of those ceilings, and retries 429 and 5xx responses with exponential backoff, honouring Retry-After.

Because a month-long report means pulling every order for 30 business dates, completed dates are cached to disk as JSON. Today and the previous TOAST_CACHE_SETTLE_DAYS days (1 by default) are always re-fetched, since tips, refunds and closeouts keep changing. Pass refresh: true to any report to bypass the cache, or run toast_clear_cache after a correction is made in Toast for an older date. Every report footer states how many dates came from cache versus live.

---

Development

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 starts a mock Toast API with hand-computed fixture data, launches the compiled server as a real child process, and drives all 19 tools over stdio as an MCP client would. It asserts the actual arithmetic (net sales, tax, tips, deferred revenue, labor cost, void totals), that GUIDs resolve to names, that pagination doesn't truncate, that the cache is used and bypassed correctly, that errors surface readably — and that nothing but GET requests plus the auth POST ever reach the API.

Layout

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

---

Troubleshooting

"Missing required environment variable(s)" — the server found no credentials. The message names the exact .env path to create. If it says a .env was read but didn't define the variable, check for a typo or a value left blank — a blank value counts as unset.

A .env value seems to be ignored — something in the real environment is overriding it, since environment variables take precedence. toast_check_connection reports which source the credentials came from. (A variable exported as empty, e.g. TOAST_CLIENT_ID=, is treated as unset and will not block the .env value.)

403 on some tools but not others — a missing scope. Run toast_check_connection; the API access table shows which are denied. Add the scope to your credential set in Toast Web.

Servers or categories show as #a1b2c3d4 — the Configuration or Labor scope isn't granted, so GUIDs can't be resolved to names. Sales figures are still correct.

Numbers differ slightly from Toast Web — expected; see the definitions table above. The most common causes are Toast's dashboard treating service charges or deferred revenue differently.

A past date looks stale — a correction was made in Toast after the date was cached. Pass refresh: true, or run toast_clear_cache.

Reports are slow the first time — a 90-day report pulls every order for 90 business dates. The second run is served from cache.