qc0624/maimai-bot repository overview

⁠MaiMai Telegram Bot

A Telegram bot that calls the McDonald's MCP tools (campaign calendar and coupons) via Streamable HTTP.

⁠Features

• Campaign calendar query (campaign-calender) via Telegraph article (with images)
• Available coupons list (available-coupons) via Telegraph article (with images)
• One-click claim all coupons (auto-bind-coupons)
• My coupons list (my-coupons)
• Optional 5-minute cache for non-user-specific tools
• Daily auto-claim (once per day) with burst scheduling when new coupons appear
• Multiple MCP accounts per Telegram user (switchable)

⁠Requirements

• Node.js 18+ (Node.js 20+ recommended)
• A Telegram bot token from BotFather
• An MCP token from https://open.mcd.cn/mcp⁠

⁠Quick Start

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

npm install

1. Start the bot:

npm start

⁠Bot Commands

• /token YOUR_MCP_TOKEN - save your MCP token
• /account add <name> <token> - add/update an account
• /account use <name> - switch active account
• /account list - list accounts
• /account del <name> - delete an account
• /calendar [YYYY-MM-DD] - campaign calendar (optional date)
• /coupons - available coupons
• /claim - one-click claim all available coupons
• /mycoupons - my coupons list
• /autoclaim on|off [name] - enable/disable daily auto-claim per account
• /autoclaimreport success|fail on|off [name] - enable/disable auto-claim reporting per account
• /status - show account status
• /stats - my claim stats
• /cleartoken - clear all accounts
• /admin users - admin stats (users/accounts/claim totals)

⁠Environment Variables

See .env.example for all options. Key variables:

• TELEGRAM_BOT_TOKEN (required)
• MCD_MCP_URL (default: https://mcp.mcd.cn/mcp-servers/mcd-mcp)
• HTTP_PROXY / HTTPS_PROXY (optional, for users in China or behind proxy)
• CACHE_TTL_SECONDS (default: 300)
• CACHEABLE_TOOLS (default: campaign-calender,available-coupons)
• AUTO_CLAIM_CHECK_MINUTES (default: 10)
• AUTO_CLAIM_HOUR (default: 9)
• AUTO_CLAIM_TIMEZONE (default: Asia/Shanghai)
• AUTO_CLAIM_SPREAD_MINUTES (default: 600)
• AUTO_CLAIM_MAX_PER_SWEEP (default: 10)
• AUTO_CLAIM_REQUEST_GAP_MS (default: 1500)
• GLOBAL_BURST_WINDOW_MINUTES (default: 30)
• GLOBAL_BURST_CHECK_SECONDS (default: 60)
• ADMIN_TELEGRAM_IDS (comma-separated Telegram user IDs for whitelist mode)
  • If set, only these users can use the bot
  • If empty, all users can use the bot
  • Get your Telegram ID by messaging the bot (it will show in the error message)

⁠Notes

• The bot uses MCP Streamable HTTP (protocol 2025-06-18).
• The MCP token is required for all tool calls.
• Telegraph access token is created automatically and stored at data/telegraph.json.
• Auto-claim runs once per account per day, scheduled across a spread window to avoid bursts.
• When any account claims a previously unseen coupon, the bot triggers a short burst window so all accounts attempt to claim within that time.

⁠Deployment

⁠1) Install 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

Verify:

node -v
npm -v

⁠2) Install the bot

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

Edit .env and set:

• TELEGRAM_BOT_TOKEN
• MCD_MCP_URL (optional)

Install dependencies:

npm install

Run once to verify:

npm start

⁠3) Run as a systemd service

Create a service file:

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

Adjust paths and user:

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

Enable and start:

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

View logs:

journalctl -u maimai-bot -f

⁠4) Update

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

⁠Docker 部署

⁠使用预构建镜像（推荐）

# 创建目录
mkdir -p maimai-bot && cd maimai-bot

# 创建 .env 文件
cat > .env << 'EOF'
TELEGRAM_BOT_TOKEN=your_token_here
MCD_MCP_URL=https://mcp.mcd.cn/mcp-servers/mcd-mcp
MCP_PROTOCOL_VERSION=2025-06-18
CACHE_TTL_SECONDS=300
AUTO_CLAIM_HOUR=9
AUTO_CLAIM_TIMEZONE=Asia/Shanghai

# 代理设置（国内用户可选）
# HTTP_PROXY=http://your-proxy:port
# HTTPS_PROXY=http://your-proxy:port
EOF

# 创建数据目录
mkdir -p data

# 启动容器
docker run -d --name maimai-bot \
  --env-file .env \
  -v ./data:/app/data \
  --restart unless-stopped \
  qc0624/maimai-bot:latest

⁠使用 Docker Compose

# docker-compose.yml
services:
  maimai-bot:
    image: qc0624/maimai-bot:latest
    container_name: maimai-bot
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    # 如需使用代理，取消注释并配置
    # environment:
    #   HTTP_PROXY: http://your-proxy:port
    #   HTTPS_PROXY: http://your-proxy:port

# 启动
docker compose up -d

# 查看日志
docker logs -f maimai-bot

# 停止
docker compose down

⁠自行构建镜像

git clone https://github.com/ButaiKirin/MaiMaiBot.git
cd MaiMaiBot
cp .env.example .env
# 编辑 .env 填入 TELEGRAM_BOT_TOKEN 和代理配置（如需要）

docker compose up -d --build

注意事项:

• 数据持久化在 ./data 目录，容器会自动处理权限
• 国内用户如遇连接问题，请配置 HTTP_PROXY 和 HTTPS_PROXY 环境变量
• 代理格式：http://host:port 或 socks5://host:port