Skip to content
Back to search

MaiMaiBot

A Telegram bot that calls the McDonald's MCP tools via Streamable HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/butaikirin--maimaibot/badge.svg)](/listings/butaikirin--maimaibot)

HTML

<a href="/listings/butaikirin--maimaibot"><img src="/api/listings/butaikirin--maimaibot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Copy `.env.example` to `.env` and fill in `TELEGRAM_BOT_TOKEN`. 2. Install dependencies:

npm install

3. Start the bot:

npm start

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 267 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MaiMai Telegram Bot
  2. A Telegram bot for McDonald's China MCP tools over Streamable HTTP.
  3. ## Current Interface Support
  4. This project is aligned with the current official MCP documentation at [https://open.mcd.cn/mcp/doc](https://open.mcd.cn/mcp/doc), including the `2026-04-02` `v1.0.3` toolset.
  5. It now handles the current interface changes:
  6. - Uses the current canonical MCP URL `https://mcp.mcd.cn`
  7. - Validates tokens through `tools/list` instead of hard-coding a single tool call
  8. - Adapts to renamed tools:
  9. - `campaign-calender` -> `campaign-calendar`
  10. - `my-coupons` -> `query-my-coupons`
  11. - Keeps compatibility with legacy tool names where possible
  12. - Isolates cache entries by token to avoid cross-account result reuse
  13. ## Features
  14. - Campaign calendar query via Telegraph article with images
  15. - Available coupons list
  16. - One-click claim all available coupons
  17. - My coupons list
  18. - My points query
  19. - Nutrition list query with keyword filtering
  20. - Points mall product list, detail, and redeem
  21. - Delivery address list and create
  22. - Nearby store search and favorite-store query
  23. - Store coupon, meal list, meal detail, price calculation, order create/query
  24. - Raw `/tool` passthrough for any currently exposed MCP tool
  25. - Optional cache for selected tools
  26. - Daily auto-claim with burst scheduling when new coupons appear
  27. - Multiple MCP accounts per Telegram user
  28. ## Requirements
  29. - Node.js 18+ (Node.js 20+ recommended)
  30. - A Telegram bot token from BotFather
  31. - An MCP token from https://open.mcd.cn/mcp
  32. ## Quick Start
  33. 1. Copy `.env.example` to `.env` and fill in `TELEGRAM_BOT_TOKEN`.
  34. 2. Install dependencies:
  35. ```bash
  36. npm install
  37. ```
  38. 3. Start the bot:
  39. ```bash
  40. npm start
  41. ```
  42. ## Bot Commands
  43. - `/help` - full command list
  44. - `/tools` - list MCP tools available to the active account
  45. Account and token:
  46. - `/token YOUR_MCP_TOKEN` - save MCP token to the active/default account
  47. - `/account add <name> <token>` - add/update an account
  48. - `/account use <name>` - switch active account
  49. - `/account list` - list accounts
  50. - `/account del <name>` - delete an account
  51. - `/cleartoken` - clear all accounts
  52. - `/status` - show account status
  53. - `/stats` - my claim stats
  54. Coupon and calendar:
  55. - `/calendar [YYYY-MM-DD]` - campaign calendar
  56. - `/coupons` - available coupons
  57. - `/claim` - one-click claim all available coupons
  58. - `/mycoupons` - my coupons list
  59. - `/autoclaim on|off [name]` - enable/disable daily auto-claim per account
  60. - `/autoclaimreport success|fail on|off [name]` - enable/disable auto-claim reporting per account
  61. Points, mall, time, nutrition:
  62. - `/points` - my points account
  63. - `/mall list` - points mall product list
  64. - `/mall detail <spuId>` - points mall product detail
  65. - `/mall redeem <skuId> [count]` - redeem a points mall item
  66. - `/nutrition [keyword]` - nutrition list (optional local keyword filter)
  67. - `/now` - MCP server current time info
  68. Store and delivery:
  69. - `/deliveryaddrs mls|group` - list delivery addresses
  70. - `/deliveryadd mls|group 城市|联系人|电话|地址|门牌|性别(可选)` - create a delivery address
  71. - `/stores fav` - query favorite in-store pickup stores
  72. - `/stores search <city> <keyword>` - search nearby stores
  73. - `/storecoupons <storeCode> <pickup|delivery> [beCode]` - list usable coupons for a store/order type
  74. - `/meals <storeCode> <pickup|delivery> [beCode]` - list meals for a store/order type
  75. - `/mealdetail <code> <storeCode> <pickup|delivery> [beCode]` - meal detail
  76. Advanced order tools:
  77. - `/price <json>` - call `calculate-price`
  78. - `/order create <json>` - call `create-order`
  79. - `/order query <orderId>` - call `query-order`
  80. - `/tool <toolName> [json]` - raw passthrough for any current MCP tool
  81. Admin:
  82. - `/admin` - admin summary (users/accounts/auto-claim status/claim totals/config/sweep状态)
  83. - `/admin notify on|off` - admin error push toggle
  84. - `/admin sweep` - run a sweep immediately (admin)
  85. ### JSON command examples
  86. ```bash
  87. /price {"storeCode":"12345","orderType":"pickup","items":[{"productCode":"9900008139","quantity":1}]}
  88. /order create {"storeCode":"12345","orderType":"pickup","takeWayCode":"locker-in","items":[{"productCode":"9900008139","quantity":1}]}
  89. /tool now-time-info
  90. ```
  91. ## Environment Variables
  92. See `.env.example` for all options. Key variables:
  93. - `MCD_MCP_URL` (default: `https://mcp.mcd.cn`)
  94. - `MCP_REQUEST_TIMEOUT_MS` (default: `30000`)
  95. - `MCP_CLIENT_CACHE_TTL_SECONDS` (default: `1800`)
  96. - `MCP_RETRY_MAX` (default: `2`)
  97. - `MCP_RETRY_BASE_DELAY_MS` (default: `500`)
  98. - `MCP_RETRY_MAX_DELAY_MS` (default: `5000`)
  99. - `MCP_RETRY_JITTER_MS` (default: `200`)
  100. - `MCP_RETRY_STATUS_CODES` (default: `502,503,504`)
  101. - `MCP_RETRY_ON_TIMEOUT` (default: `true`)
  102. - `MCP_RETRY_ON_NETWORK_ERROR` (default: `true`)
  103. - `MCP_HEALTH_CHECK_INTERVAL_MS` (default: `60000`)
  104. - `MCP_HEALTH_CHECK_TIMEOUT_MS` (default: `5000`)
  105. - `MCP_HEALTH_FAILURE_THRESHOLD` (default: `2`)
  106. - `MCP_UPSTREAM_ERROR_MESSAGE` (default: Chinese "upstream error")
  107. - `ACCOUNT_ID_MIN_LENGTH` (default: `1`)
  108. - `ACCOUNT_ID_MAX_LENGTH` (default: `32`)
  109. - `TOKEN_MIN_LENGTH` (default: `16`)
  110. - `TOKEN_MAX_LENGTH` (default: `256`)
  111. - `TOKEN_SET_RATE_LIMIT_MS` (default: `30000`)
  112. - `ACCOUNT_SET_RATE_LIMIT_MS` (default: `30000`)
  113. - `CACHE_TTL_SECONDS` (default: `300`)
  114. - `CACHEABLE_TOOLS` (default: `campaign-calendar,list-nutrition-foods`)
  115. - `AUTO_CLAIM_CHECK_MINUTES` (default: `10`)
  116. - `AUTO_CLAIM_HOUR` (default: `9`)
  117. - `AUTO_CLAIM_TIMEZONE` (default: `Asia/Shanghai`)
  118. - `AUTO_CLAIM_SPREAD_MINUTES` (default: `600`)
  119. - `AUTO_CLAIM_MAX_PER_SWEEP` (default: `10`)
  120. - `AUTO_CLAIM_REQUEST_GAP_MS` (default: `1500`)
  121. - `AUTO_CLAIM_SPREAD_RERUN_MINUTES` (default: `120`)
  122. - `GLOBAL_BURST_WINDOW_MINUTES` (default: `30`)
  123. - `GLOBAL_BURST_CHECK_SECONDS` (default: `30`)
  124. - `ADMIN_TELEGRAM_IDS` (comma-separated Telegram user IDs)
  125. - `SWEEP_WATCHDOG_SECONDS` (default: `60`)
  126. - `SWEEP_STALE_MULTIPLIER` (default: `2`)
  127. - `AUTO_CLAIM_DEBUG` (default: `false`, set to `true`/`1` to enable verbose auto-claim logs)
  128. ## Notes
  129. - The bot uses MCP Streamable HTTP (protocol 2025-06-18).
  130. - The MCP token is required for all tool calls.
  131. - Official docs: [https://open.mcd.cn/mcp/doc](https://open.mcd.cn/mcp/doc)
  132. - Telegraph access token is created automatically and stored at `data/telegraph.json`.
  133. - Auto-claim runs once per account per day, scheduled across a spread window to avoid bursts.
  134. - When any account claims a previously unseen coupon, the bot triggers a short burst window so all accounts attempt to claim within that time.
  135. ## Deployment
  136. ### 1) Install Node.js
  137. ```bash
  138. sudo apt update
  139. sudo apt install -y git curl
  140. curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 178 on GitHub
  141. sudo apt install -y nodejs
  142. ```
  143. Verify:
  144. ```bash
  145. node -v
  146. npm -v
  147. ```
  148. ### 2) Install the bot
  149. ```bash
  150. git clone https://github.com/ButaiKirin/MaiMaiBot.git
  151. cd MaiMaiBot
  152. cp .env.example .env
  153. ```
  154. Edit `.env` and set:
  155. - `TELEGRAM_BOT_TOKEN`
  156. - `MCD_MCP_URL` (optional)
  157. Install dependencies:
  158. ```bash
  159. npm install
  160. ```
  161. Run once to verify:
  162. ```bash
  163. npm start
  164. ```
  165. ### 3) Run as a systemd service
  166. Create a service file:
  167. ```bash
  168. sudo tee /etc/systemd/system/maimai-bot.service > /dev/null <<'SERVICE'
  169. [Unit]
  170. Description=MaiMai Telegram Bot
  171. After=network.target
  172. [Service]
  173. Type=simple
  174. WorkingDirectory=/opt/MaiMaiBot
  175. EnvironmentFile=/opt/MaiMaiBot/.env
  176. ExecStart=/usr/bin/node /opt/MaiMaiBot/src/index.js
  177. Restart=always
  178. RestartSec=5
  179. User=ubuntu
  180. Group=ubuntu
  181. [Install]
  182. WantedBy=multi-user.target
  183. SERVICE
  184. ```
  185. Adjust paths and user:
  186. ```bash
  187. sudo mkdir -p /opt
  188. sudo mv ~/MaiMaiBot /opt/MaiMaiBot
  189. sudo chown -R ubuntu:ubuntu /opt/MaiMaiBot
  190. ```
  191. Enable and start:
  192. ```bash
  193. sudo systemctl daemon-reload
  194. sudo systemctl enable --now maimai-bot
  195. ```
  196. View logs:
  197. ```bash
  198. journalctl -u maimai-bot -f
  199. ```
  200. ### 4) Update
  201. ```bash
  202. cd /opt/MaiMaiBot
  203. git pull
  204. npm install
  205. sudo systemctl restart maimai-bot
  206. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.