vxcn/mcd-kcal-picker

A small read-only Skill that turns a calorie target into a concrete McDonald's China combo. It is useful as a working example of a commercial MCP integration, but its nutrition data path depends on a token you must obtain yourself and its search space is limited to what the official list returns.

The problem

You want a McDonald's meal that lands near, say, 600 kcal without exceeding 700, and you would rather not open a nutrition table and add up items by hand. Before this project, that meant browsing item pages, mentally combining a main, a side and a drink, then rechecking the totals. Here a script calls the official MCP read-only nutrition tool, pulls the food list into a JSON file, and hands it to a deterministic picker. You get one combination with per-item calories and combined protein, fat, carbohydrates and sodium, or an explicit statement that no combination fits under the cap.

What's different

The interesting design choice is that the language model does not do the arithmetic. The README describes a clear split: the MCP takes care of fetching official nutrition data, and a small Python script does the combinatorial selection project instructions. That means the result is reproducible and auditable rather than a plausible-looking number generated by a model. The picker also honors simple exclusion filters, so you can ask for combinations without a particular item attribute such as a spicy item, and it reports failure honestly instead of returning an over-limit result.

The trade-off is scope. The repository explicitly does only one thing: call list-nutrition-foods and compute a combination; it does not order, claim coupons, manage points or call write tools project instructions. The bundled demo data is sample data, not live official data, so the demo proves the flow rather than the current menu. The two scripts have no third-party dependencies, which keeps setup light, but it also means this is a thin utility rather than a full meal-planning application.

Who should try it

Good fit: someone who wants a quick calorie-bounded McDonald's China combo and is willing to set up a token, or a developer who wants a small, readable reference for how a commercial MCP server can be wrapped by a Skill and a script. The SKILL.md plus scripts plus references layout is also a reasonable template if you are structuring your own agent skill. Poor fit: anyone who wants ordering, price comparison, dietary medical advice or a polished app; the project deliberately stops at choosing a combination, and it presents output as reference only.

Requirements and limitations

Demo mode runs with Python 3 and no token, which makes it a quick way to see the output shape. Real data requires your own MCP token from the McDonald's MCP open platform, passed only through the MCD_MCP_TOKEN environment variable; the repository contains no credentials project instructions. You have to fetch the food list to a file first, then run the picker against that file, so the workflow is two commands rather than one seamless query.

The result is only as current as the official tool's response, and the README says item information, prices and availability should be checked against official channels. There is no license declared, which matters if you intend to reuse the code beyond personal experimentation. The project is also explicitly a contest entry, independent of McDonald's, not an official product.

HotRepo's take

The repository was created on 2026-10-24 and appeared on HotRepo's NEW-REPOSITORY board for Python at #23 with 156 total stars, observed 2026-10-25 project instructions. That is a one-day snapshot from a new-repository board, not an overall Trending rank or a daily growth measurement. With only that coverage, persistence cannot be judged. Before adopting it, check the token application and official MCP documentation path, since that is the gate between the demo and real menu data.