Toast MCP Server

Toast POS API용 읽기 전용 Model Context Protocol 서버입니다. AI 어시스턴트가 레스토랑에 대한 질문에 답하고 라이브 Toast 데이터에서 직접 매출, 인건비, 현금 보고서를 생성할 수 있게 해줍니다.

Toast에 절대 쓰기 작업을 하지 않습니다. HTTP 클라이언트는 GET 요청만 보내며, 코드베이스의 단일 POST는 Toast가 토큰 발급을 위해 요구하는 인증 호출로, src/auth.ts에 격리되어 있습니다. 스모크 테스트가 이를 검증합니다.

무엇을 물어볼 수 있나요

연결되면 다음과 같은 질문이 작동합니다:

• "지난주는 그 전주에 비해 어땠나요?"

• "7월 순매출 상위 20개 품목과 각각의 평균 가격은 무엇인가요?"

• "지난 토요일 시간대별 매출을 분석해 주세요 — 실제 저녁 러시는 언제인가요?"

• "이번 달 현금 대 카드 비중은 어떻게 되고, 카드 처리 수수료는 얼마나 냈나요?"

• "어떤 할인이 가장 많이 사용되고, 얼마나 사용되었나요?"

• "지난 2주간의 모든 보이드와 사유, 근무자 정보를 보여주세요."

• "지난달 인건비는 순매출 대비 몇 퍼센트였고, 직원별로 어떻게 되나요?"

• "지금 86 처리된 품목은 무엇인가요?"

• "금요일 밤의 $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. client ID와 client secret을 복사합니다 — secret은 한 번만 표시됩니다.

  계정에 해당 옵션이 없다면 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를 사용합니다. 자격 증명에는 두 가지 옵션이 있으며 하나만 있으면 됩니다:

• .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

문제 해결

"필수 환경 변수 누락" — 서버가 자격 증명을 찾지 못했습니다. 메시지는 생성해야 할 정확한 .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개의 영업일 동안 모든 주문을 가져옵니다. 두 번째 실행은 캐시에서 제공됩니다.