holdcloud/mcd-calendar-buddy

A contest entry, not a polished product: it is a small, zero-dependency Python CLI that turns McDonald's China campaign listings into calendar events. Worth a look if you already live in Calendar.app and use the official McDonald's MCP service; otherwise the token requirement and macOS focus narrow its appeal.

The problem

You want the limited-edition burger launch or coupon window to appear in your schedule before it sells out, but the information lives in a promotional feed you would have to check manually. Copying dates into Calendar.app by hand is the step that usually gets skipped. This tool queries the McDonald's MCP campaign-calendar tool, parses the returned Markdown into events, and writes them into a dedicated calendar with reminders attached. The result is a recurring sync workflow rather than one more page to remember to open.

What's different

The interesting design choice is how reminders are derived from the activity text. If the description contains a precise sale start such as a date and time, the tool schedules two alerts, one day and one hour before; all-day campaigns get a single reminder at 09:00 the previous day. That distinction is more useful than a blanket reminder, and it is configurable with --remind-days. Event identity is handled with UIDs, so re-running sync skips already-written events instead of duplicating them.

Cross-platform use rests on .ics export as the fallback. Only macOS gets direct Calendar.app writes, via AppleScript and a separate automation permission. The schedule command generates a launchd job that runs daily, but that path is macOS-only. Keyword filtering is simple comma-separated matching on title/description text, so it is convenient and also brittle if an activity is only loosely named. Parsing depends on the shape of McDonald's Markdown, and the README claims eight unit tests around parsing and fallback behavior, not a guarantee against upstream format changes.

Who should try it

Good fit: a macOS user in mainland China who already has a McDonald's MCP token, treats Calendar.app as the source of truth, and wants campaign reminders without checking a feed. The built-in sync plus schedule path is the intended experience there. Poor fit: anyone without a token, or who does not want another service credential stored in an environment variable, since the query path does not work without it. Users on Windows or Linux can still use query and export -o mc.ics and import the file, but they lose direct calendar writes and should not expect schedule to manage a daily job for them; the documented one-line install prompts for AI agents assume the token is obtained from the official MCP site.

Requirements and limitations

Python 3.10+ and a working MCD_MCP_TOKEN are the hard prerequisites; the README describes obtaining it by logging into the McDonald's MCP site and activating it in the console. No third-party dependencies are needed for the runtime, which keeps setup small. macOS direct sync triggers a Calendar automation permission prompt the first time, which must be granted in System Settings; declining it leaves only the .ics route. The license badge says MIT, but the repository metadata lists no declared license, so check the actual license file before redistributing.

Ongoing upkeep matters more than installation: parsing, filtering and reminder extraction all follow McDonald's feed format, and there is no documented monitoring beyond the CI test badge. If the feed's Markdown changes, malformed events are the likely symptom, so inspect the first query output before trusting sync with a large batch. Also, the project explicitly states it is not an official McDonald's product and that official channels are authoritative, which limits it to personal reminder convenience.

HotRepo's take

On 2026-10-25 the project appeared on HotRepo's NEW-REPOSITORY board for Python at #19 with 152 total stars, tracked only since 2026-10-24. That is a young-repository snapshot, not evidence of staying power; comparable daily history is insufficient to judge persistence. Before relying on it, verify that your MCP token still returns the campaign-calendar payload the parser expects.

Project source and documentation