Toast MCP Server

Toast POS API 用の読み取り専用 Model Context Protocol サーバーです。AI アシスタントが、レストランに関する質問に答えたり、ライブの Toast データから売上・人件費・現金レポートを生成したりできるようにします。

Toast への書き込みは一切行いません。HTTP クライアントは GET リクエストのみを発行します。コードベース内の唯一の POST は、Toast がトークンを発行するために必要な認証呼び出しであり、src/auth.ts に分離されています。スモークテストはこれを検証します。

質問できる内容

接続すると、次のような質問が機能します。

• 「先週は前週と比べてどうでしたか？」

• 「7月の純売上上位20品目と、それぞれの平均価格は？」

• 「先週の土曜日の時間別売上を教えて。実際のディナーラッシュはいつ？」

• 「今月の現金とカードの割合は？カード処理手数料はいくら支払いましたか？」

• 「最も使われている割引はどれで、その金額は？」

• 「過去2週間のすべてのボイドを、理由と担当者とともに表示して」

• 「先月の人件費は純売上に対して何パーセントでしたか？従業員別で」

• 「現在、売り切れ（86'd）になっているものは？」

• 「金曜の夜の340ドルの注文を見つけて、その内容を表示して」

• 「日曜日の営業時間は？また、設定されているダイニングオプションは？」

Related MCP server: Shopify MCP Server

要件

• Node.js 20 以降（Node 22 でビルド・テスト済み）。

• Toast API 資格情報。 自社データをレポートするレストランの場合、適切な製品は Standard API Access です。これは設計上読み取り専用で、セルフサービスです。

  1. Toast Web で、Integrations → Toast API access → Manage credentials に移動します。

  2. 資格情報セットを作成し、名前を付け（例: mcp-reporting）、以下の読み取りスコープを選択します。

  3. クライアント ID と クライアントシークレット をコピーします。シークレットは一度しか表示されません。

  アカウントにそのオプションがない場合、それは Restaurant Management Essentials の一部です。Toast の担当者が有効化できます。パートナー統合の場合は、代わりに Toast 統合チームから資格情報を取得します。

有効にするスコープ

コアの売上レポートには orders:read、config:read、restaurants:read のみが必要です。スコープが不足している場合、サーバーは正常に縮退します。影響を受けるツールは拒否を報告し、他のツールは動作し続けます。toast_check_connection を実行して、付与されている内容を正確に確認してください。

また、レストラン GUID も必要です。toast_check_connection がそれを報告するか、Toast Web の URL でロケーションが選択されているときに確認するか、管理グループ GUID を使用して toast_list_restaurants を使用します。

インストール

npm install && npm run build

次に、環境テンプレートをコピーして記入します。

cp .env.example .env

最低限 TOAST_CLIENT_ID、TOAST_CLIENT_SECRET、TOAST_RESTAURANT_GUID を設定します。サーバーはこのファイルを自動的に読み取ります（Node のネイティブ env-file サポート経由）。.env は gitignore されています。

配線する前に資格情報を検証します。

npm run check-connection

これにより、環境、付与されたスコープ、レストラン名、タイムゾーン、締め時間、現在の営業日が出力されます。

Claude に接続する

サーバーは stdio 経由で MCP を話します。資格情報には2つのオプションがあり、1つだけで十分です。

• .env に残す。 サーバーは、クライアントが起動する作業ディレクトリに関係なく、自身のパッケージディレクトリから .env を読み込むため、以下の設定は env ブロックなしで機能します。シークレットはクライアントの設定ファイルに残りません。

• クライアントの env ブロックに入れる（下記参照）。実際の環境変数は常に .env より優先されるため、両方存在する場合はこれが優先されます。

Claude Code

.env を記入した場合、これだけで十分です。コマンドに資格情報は不要です。

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

資格情報を明示的に渡す場合:

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

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

.env を使用している場合は、env ブロックを完全に削除します。Windows では、パスにフォワードスラッシュまたはエスケープされたバックスラッシュを使用します。

設定

ツール

接続とセットアップ

レポート

ルックアップ

日付

すべてのレポートは、レストラン自身のタイムゾーンで営業日に基づき、設定された締め時間を尊重します。つまり、土曜日の午前2時の売上は、Toast のレポートと同様に、金曜日の営業日に計上されます。

date_range でプリセット（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）を使用するか、start_date / end_date でその他の日付を指定します。これらは 2026-08-01、20260801、today、yesterday、または -7d、-2w、-3m のような相対オフセットを受け入れます。何も指定しない場合のデフォルトは昨日です。

数値の定義

これらは生の注文データから取得されるため、追加の会計ルールを適用する Toast Web のレポートとはわずかに異なる場合があります。各レポートは、出力でその定義を再述します。

知っておくべき微妙な点が1つある。 Toast のデータモデルでは、明細項目の price と preDiscountPrice には、ネストされたモディファイアの価格がすでに含まれている。親項目に加えてモディファイアを合計すると、すべての追加料金が二重計上される。このサーバーは常にトップレベルの選択項目のみを合計し、テストスイートはモディファイアが2回カウントされないことを検証する。

2つの前提が該当箇所に明記されている。人件費の見積もりは、記録上の時給の 1.5倍 を時間外として計算する（Toast は実際の時間外料金を報告しない。乗数はツールの引数である）。また、記録上の時給がない時間エントリは、時間数にはカウントされるがコストにはカウントされない。

レート制限とキャッシュ

Toast は全体で毎秒20リクエスト、ordersBulk は毎秒5リクエスト、menus は毎秒1リクエストを許可している。サーバーはこれらの上限を下回るトークンバケット方式のリミッターを実行し、429 および 5xx レスポンスに対しては指数バックオフで再試行し、Retry-After を尊重する。

1か月分のレポートは30営業日分のすべての注文を取得することを意味するため、完了した日付はJSONとしてディスクにキャッシュされる。今日と過去 TOAST_CACHE_SETTLE_DAYS 日分（デフォルトは1日）は、チップ、返金、締め処理が変わり続けるため、常に再取得される。任意のレポートに refresh: true を渡すとキャッシュをバイパスできる。また、過去の日付について Toast で修正を行った後は toast_clear_cache を実行できる。各レポートのフッターには、キャッシュから取得された日付とライブで取得された日付の数が記載される。

開発

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 は手計算されたフィクスチャデータでモック Toast API を起動し、コンパイル済みサーバーを実際の子プロセスとして起動し、MCP クライアントが行うように stdio 経由で19個すべてのツールを駆動する。実際の算術（純売上、税、チップ、繰延収益、人件費、無効化合計）が正しいこと、GUID が名前に解決されること、ページネーションが切り詰められないこと、キャッシュが正しく使用・バイパスされること、エラーが読みやすく表示されること、そして GET リクエストと認証用 POST 以外は API に到達しないことを検証する。

構成

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

トラブルシューティング

「必須環境変数がありません」 — サーバーが認証情報を見つけられなかった。メッセージには作成すべき正確な .env パスが記載されている。.env は読み取られたが変数が定義されていないと表示された場合は、タイプミスや空白のままの値がないか確認すること — 空白の値は未設定として扱われる。

.env の値が無視されているように見える — 環境変数が優先されるため、実際の環境の何かがそれを上書きしている。toast_check_connection は認証情報がどのソースから来たかを報告する。（空でエクスポートされた変数、例: TOAST_CLIENT_ID= は未設定として扱われ、.env の値をブロックしない。）

一部のツールでのみ 403 が発生する — スコープが不足している。toast_check_connection を実行すること。API アクセステーブルに拒否されたものが表示される。Toast Web の認証情報セットにスコープを追加すること。

サーバーやカテゴリが #a1b2c3d4 と表示される — Configuration または Labor スコープが付与されていないため、GUID を名前に解決できない。売上数値は依然として正しい。

数値が Toast Web とわずかに異なる — 想定内。上記の定義表を参照のこと。最も一般的な原因は、Toast のダッシュボードがサービス料または繰延収益を異なる方法で扱っていることである。

過去の日付が古く見える — 日付がキャッシュされた後に Toast で修正が行われた。refresh: true を渡すか、toast_clear_cache を実行すること。

最初のレポートが遅い — 90日間のレポートは90営業日分のすべての注文を取得する。2回目の実行はキャッシュから提供される。