Toast MCP Server

一个用于 Toast POS API 的只读 Model Context Protocol 服务器。它让 AI 助手能够直接根据实时 Toast 数据回答关于您餐厅的问题，并生成销售、人工和现金报告。

它从不写入 Toast。HTTP 客户端仅发出 GET 请求；代码库中唯一的 POST 是 Toast 要求用于生成令牌的身份验证调用，并且它被隔离在 src/auth.ts 中。冒烟测试对此进行了断言。

您可以询问什么

连接后，类似这样的问题都可以使用：

• “我们上周与再前一周相比表现如何？”

• “7 月份净销售额前 20 的商品是哪些，每件商品的平均价格是多少？”

• “按小时细分上周六的销售额——我们真正的晚餐高峰是什么时候？”

• “这个月我们的现金与银行卡比例是多少，我们支付了多少银行卡处理费？”

• “哪些折扣使用最多，折扣金额是多少？”

• “显示过去两周内每一笔作废记录，包括原因和当班人员。”

• “上个月按员工计算，人工占净销售额的百分比是多少？”

• “我们现在有哪些菜品已售罄（86'd）？”

• “找到周五晚上的那笔 340 美元订单，并显示其包含的内容。”

• “我们周日的营业时间是什么，我们配置了哪些用餐选项？”

Related MCP server: Shopify MCP Server

要求

• Node.js 20 或更高版本（在 Node 22 上构建和测试）。

• Toast API 凭据。 对于报告自身数据的餐厅，合适的产品是 标准 API 访问，它按设计是只读且自助式的：

  1. 在 Toast Web 中，转到 集成 → Toast API 访问 → 管理凭据。

  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 中找到它，或者使用 toast_list_restaurants 配合管理组 GUID。

安装

npm install && npm run build

然后复制环境模板并填写：

cp .env.example .env

至少设置 TOAST_CLIENT_ID、TOAST_CLIENT_SECRET 和 TOAST_RESTAURANT_GUID。服务器会自动读取此文件（通过 Node 的原生环境文件支持），并且 .env 已被 gitignore。

在连接任何内容之前验证凭据：

npm run check-connection

这将打印环境、授予的范围、餐厅名称、其时区和结算小时，以及当前业务日期。

连接到 Claude

服务器通过 stdio 使用 MCP 通信。您有两种凭据选项，只需选择一种：

• 将它们留在 .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 自身报告略有差异，后者会叠加额外的会计规则。每个报告都会在其输出中重申其定义。

一个值得了解的细节。 在 Toast 的数据模型中，行项目的 price 和 preDiscountPrice 已经包含其嵌套修饰项的价格。在父项之上累加修饰项会重复计算每次加价。此服务器只累加顶层选项，测试套件会断言修饰项不会被计算两次。

两个假设在适用处均有说明：人工成本按记录时薪的 1.5× 估算加班费（Toast 不报告实际加班费率；倍率是工具参数），以及没有记录时薪的时间条目只计入工时但不计入成本。

速率限制与缓存

Toast 允许总体每秒 20 个请求，ordersBulk 每秒 5 个，menus 每秒 1 个。服务器在每个上限之下运行令牌桶限流器，并以指数退避重试 429 和 5xx 响应，同时遵循 Retry-After。

由于月度报告意味着要拉取 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

故障排查

"Missing required environment variable(s)" — 服务器未找到凭据。该消息会指明要创建的精确 .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 个营业日期的每一笔订单。第二次运行将从缓存提供。