MaiMaiBot：基于 MCP 协议的麦当劳优惠券自动领取 Telegram 机器人技术分析

一、项目概述

1. 项目背景

MaiMaiBot 是一个开源的 Telegram 机器人项目，通过集成麦当劳 MCP（Model Context Protocol）服务器，实现了活动日历查询、优惠券列表获取以及一键自动领取等功能。该项目采用 Node.js 开发，利用 MCP Streamable HTTP 协议与麦当劳后端服务进行通信。

2. 核心功能

A. 主要功能

  • 活动日历查询：通过 Telegraph 文章形式展示，包含图片
  • 可用优惠券列表：以 Telegraph 文章形式展示，包含图片
  • 一键领取所有优惠券：自动绑定所有可领取的优惠券
  • 我的优惠券列表：查看已领取的优惠券
  • 每日自动领取：每个账号每天自动执行一次领取任务
  • 多账号管理：支持每个 Telegram 用户管理多个 MCP 账号

B. 技术亮点

  • MCP Streamable HTTP 协议集成（2025-06-18 版本协议）
  • Telegraph 自动化文章生成
  • 智能缓存机制（5 分钟 TTL）
  • 分布式自动领取调度，避免请求突发
  • 全局突发窗口机制，新优惠券出现时触发批量领取

二、系统架构

1. 架构设计

graph TB
    User[Telegram 用户] --> TG[Telegram Bot API]
    TG --> Bot[MaiMaiBot 服务]
    Bot --> Cache[(缓存层)]
    Bot --> MCP[麦当劳 MCP 服务器]
    Bot --> Telegraph[Telegraph API]
    Bot --> Storage[(JSON 存储)]
    Bot --> Scheduler[定时调度器]

    Scheduler --> Bot
    Telegraph --> User

MaiMaiBot 系统架构图

2. 核心组件

A. index.js

主入口文件，负责 Telegram Bot 的初始化、命令路由和消息处理。

B. mcpClient.js

MCP 客户端封装，处理与麦当劳 MCP 服务器的通信，包括 Streamable HTTP 协议的实现。

C. cache.js

缓存模块，为非用户特定的工具调用提供 5 分钟 TTL 缓存。

D. storage.js

数据持久化模块，使用 JSON 文件存储用户账号、统计数据等信息。

E. telegraph.js

Telegraph 集成模块，自动创建访问令牌并将优惠券信息格式化为 Telegraph 文章。

F. time.js

时间调度模块，处理自动领取任务的分布式调度和突发窗口逻辑。

3. 依赖关系

graph LR
    Bot[index.js] --> MCP[mcpClient.js]
    Bot --> Cache[cache.js]
    Bot --> Storage[storage.js]
    Bot --> Telegraph[telegraph.js]
    Bot --> Time[time.js]
    MCP --> Cache

组件依赖关系图

三、技术实现

1. MCP 协议集成

A. Streamable HTTP

项目使用 MCP Streamable HTTP 协议（2025-06-18 版本）与麦当劳服务器通信。该协议支持流式响应，适合处理大量优惠券数据。

B. 工具调用

支持以下 MCP 工具：

  • campaign-calender：活动日历查询
  • available-coupons：可用优惠券列表
  • auto-bind-coupons：自动绑定优惠券
  • my-coupons：我的优惠券列表

C. 认证机制

所有工具调用需要 MCP Token，该 Token 从 https://open.mcd.cn/mcp 获取。

2. Telegraph 集成

A. 自动令牌创建

首次运行时自动创建 Telegraph 访问令牌，存储在 data/telegraph.json 文件中。

B. 文章生成

将活动日历和优惠券列表转换为 Telegraph 文章格式，包含：

  • 富文本内容
  • 图片嵌入
  • 响应式布局

C. 优势

  • 无需在 Telegram 消息中传输大量数据
  • 文章永久链接，方便分享
  • 支持复杂排版和图片展示

3. 缓存策略

A. 缓存配置

  • 默认 TTL：300 秒（5 分钟）
  • 可缓存工具：campaign-calender、available-coupons
  • 缓存键：基于工具名称和参数生成

B. 缓存价值

  • 减少 MCP 服务器调用次数
  • 降低响应延迟
  • 节省网络带宽

4. 自动领取调度

A. 调度策略

  • 每个账号每天执行一次自动领取
  • 默认执行时间：上午 9 点（Asia/Shanghai 时区）
  • 分散窗口：600 分钟（10 小时），避免请求集中

B. 突发窗口机制

当任何账号领取到之前未见的优惠券时，触发全局突发窗口：

  • 突发窗口时长：30 分钟
  • 所有账号在此窗口内尝试领取
  • 每轮最多处理 10 个账号
  • 请求间隔：1.5 秒
sequenceDiagram
    participant S as 调度器
    participant A1 as 账号1
    participant A2 as 账号2
    participant MCP as MCP 服务器

    S->>A1: 执行自动领取
    A1->>MCP: 获取可用优惠券
    MCP-->>A1: 返回优惠券列表
    A1->>MCP: 领取优惠券
    A1->>A1: 发现新优惠券
    A1->>S: 触发突发窗口

    S->>A2: 立即执行领取
    S->>A1: 再次执行领取
    Note over S,A2: 突发窗口 30 分钟

自动领取调度时序图

5. 多账号管理

A. 账号操作命令

  • /account add ：添加或更新账号
  • /account use ：切换当前活动账号
  • /account list：列出所有账号
  • /account del ：删除账号
  • /cleartoken：清除所有账号

B. 数据隔离

每个 Telegram 用户的账号数据独立存储，互不干扰。

6. 统计功能

A. 用户统计

  • 个人领取统计：/stats
  • 管理员统计：/admin users（需要配置 ADMIN_TELEGRAM_IDS）

B. 统计数据

  • 领取成功次数
  • 领取失败次数
  • 总计领取次数
  • 按账号统计

四、部署指南

1. 环境要求

  • Node.js 18+（推荐 Node.js 20+）
  • Telegram Bot Token（从 BotFather 获取）
  • MCP Token（从 https://open.mcd.cn/mcp 获取）

2. 安装步骤

A. 安装 Node.js

sudo apt update
sudo apt install -y git curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node -v
npm -v

B. 部署 Bot

git clone https://github.com/ButaiKirin/MaiMaiBot.git
cd MaiMaiBot
cp .env.example .env

# 编辑 .env 文件，配置必要参数
nano .env

C. 配置环境变量

# 必须配置
TELEGRAM_BOT_TOKEN=your_bot_token_here

# 可选配置
MCD_MCP_URL=https://mcp.mcd.cn/mcp-servers/mcd-mcp
CACHE_TTL_SECONDS=300
AUTO_CLAIM_HOUR=9
AUTO_CLAIM_TIMEZONE=Asia/Shanghai
ADMIN_TELEGRAM_IDS=123456789,987654321

D. 启动服务

npm install
npm start

3. Systemd 服务配置

A. 创建服务文件

sudo tee /etc/systemd/system/maimai-bot.service > /dev/null <<'SERVICE'
[Unit]
Description=MaiMai Telegram Bot
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/MaiMaiBot
EnvironmentFile=/opt/MaiMaiBot/.env
ExecStart=/usr/bin/node /opt/MaiMaiBot/src/index.js
Restart=always
RestartSec=5
User=ubuntu
Group=ubuntu

[Install]
WantedBy=multi-user.target
SERVICE

B. 移动文件并设置权限

sudo mkdir -p /opt
sudo mv ~/MaiMaiBot /opt/MaiMaiBot
sudo chown -R ubuntu:ubuntu /opt/MaiMaiBot

C. 启动服务

sudo systemctl daemon-reload
sudo systemctl enable --now maimai-bot

D. 查看日志

journalctl -u maimai-bot -f

4. 更新流程

cd /opt/MaiMaiBot
git pull
npm install
sudo systemctl restart maimai-bot

五、技术亮点

1. MCP 协议应用

该项目是 MCP 协议的实际应用案例，展示了如何使用 MCP Streamable HTTP 协议集成第三方服务。MCP（Model Context Protocol）是 2025 年新兴的模型上下文协议标准，支持 AI 应用与外部服务的标准化交互。

2. 智能调度算法

分布式调度 + 突发窗口的组合策略，既保证了自动领取的及时性，又避免了请求集中导致的限流风险。

3. Telegraph 深度集成

利用 Telegraph 作为内容展示层，解决了 Telegram 消息长度限制和图片展示问题，提供了更好的用户体验。

4. 轻量级架构

  • 无数据库依赖，使用 JSON 文件存储
  • 核心依赖仅 2 个（dotenv、telegraf）
  • 单文件部署，易于维护

六、项目状态

1. 基本信息

2. 开发活跃度

项目近期活跃更新，主要更新包括：

  • 用户领取统计跟踪和报告功能
  • 管理员命令和 Telegram 用户 ID 配置
  • Telegraph 文章支持
  • 自动领取扩散配置和细粒度报告

七、使用场景

1. 个人使用

方便快捷地查看和领取麦当劳优惠券，无需手动操作官方 App 或小程序。

2. 多账号管理

适合需要管理多个麦当劳账号的用户，可以集中管理所有账号的优惠券。

3. 自动化领取

设置每日自动领取后，无需手动操作，确保不错过任何新优惠券。

八、安全考虑

1. Token 管理

  • MCP Token 应妥善保管，避免泄露
  • 建议使用环境变量存储敏感信息
  • 定期更新 Token

2. 访问控制

  • 通过 ADMIN_TELEGRAM_IDS 配置管理员权限
  • 每个用户只能访问自己的账号数据

3. 请求限流

  • 内置请求间隔控制（1.5 秒）
  • 突发窗口机制避免请求集中
  • 缓存机制减少服务器调用

九、总结

MaiMaiBot 是一个设计精巧的 Telegram 机器人项目，展示了 MCP 协议在实际场景中的应用。项目采用轻量级架构，功能完善，代码简洁，是学习 MCP 协议集成和 Telegram Bot 开发的良好参考。

项目的核心价值在于：

  1. 自动化优惠券领取，提升用户体验
  2. 智能调度策略，避免服务限流
  3. Telegraph 深度集成，优化内容展示
  4. 多账号管理，满足复杂需求

该项目代表了 2025 年 MCP 协议生态发展的一个缩影，随着 MCP 协议的普及，预计会有更多类似的集成应用涌现。

参考资料

  1. MaiMaiBot GitHub 仓库
  2. 麦当劳 MCP 开放平台
  3. Telegraph API 文档
  4. Telegraf.js 文档
  5. MCP 协议规范
最后修改：2026 年 01 月 18 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏