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?"

Related MCP server: Shopify MCP Server

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

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

Tools

Connection and setup

Reporting

Lookup

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.

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.