A small repository is spreading among developers who like both agents and fast food: yeqv111/mccarbon estimates the carbon footprint of your McDonald's orders from your own order history. It reads the data through McDonald's China's official MCP server, applies a three-layer emissions model (dish, packaging, delivery), and writes a single-file HTML "carbon ledger" with a grade from A to E. The repository is MIT licensed, had about 1,600 stars and 37 forks when we looked on October 24, 2026, and has only four commits.
It is a neat, honest example of what a personal-data MCP integration can look like, and a useful case to study for its caveats: the numbers are estimates built mostly from category medians, and live use requires handing the tool a personal token.
TL;DR: the questions people are asking #
| Question | Answer |
|---|---|
| What does it do? | Turns McDonald's China order history into a CO2e report and reduction simulator |
| Official? | No. Contest entry in McDonald's Programmer's Day creative development contest, per the README |
| License and language | MIT, Python 3.9+, no third-party dependencies |
| Data source | Official McDonald's MCP (token required for live data) |
| Try without a token? | Yes, PYTHONPATH=src python3 -m mccarbon demo uses built-in 2026 sample data |
| How accurate? | Estimates; many items use category medians, not measurements |
| Output | Self-contained HTML, no external CDN |
| Privacy | Membership card numbers masked by default |
How the three-layer model works #
The README breaks the footprint of a meal into three layers, each calculated separately and itemized in the report.
1. The dish layer (about 90% of the total, per the README). Some items use published measured values from the Vegan Society's "Plate Up For The Planet" report, in kg CO2e per serving for the UK: Double Big Mac 4.46, Quarter Pounder 2.99, Big Mac 2.35, 20 McNuggets 2.13, Filet-O-Fish 0.82, McPlant 0.29, McFlurry 0.17 and large fries 0.15. For categories, it cites ADEME's Agribalyse database (fast-food burgers at 18.6 kg CO2e per kg, about 92.5% from agriculture) and a European beef life-cycle figure of 23.5 kg CO2e per kg.
2. The packaging layer. Using a Chinese product life-cycle greenhouse-gas factor database, it assigns about 186.18 g CO2e to a 650 mL polypropylene takeaway box, about 54 g to a cutlery set and about 19 g to a 6 g plastic bag. Packaging is allocated by channel, so delivery orders carry much more than dine-in or pickup.
3. The delivery layer. From domestic food-delivery research, the README uses about 111.80 g CO2e per order on average, of which 86% is packaging and the ride itself about 15.6 g, mostly electric two-wheelers. The README concludes that choosing pickup nearly removes this layer.
The README does not spell out the exact formula, though it says combo meals are expanded into single items first and that the longest matching keyword wins when matching dish names. Factor tables (DISH_FACTORS, CATEGORY_SERVING_KG) live in factors.py, so anyone can audit them.
The honest part: what is measured and what is guessed #
The README is upfront: figures are estimates "for horizontal comparison and identifying reduction opportunities," not McDonald's official data, and it makes no environmental claims. The biggest caveat is the one it states itself: most items on the Chinese menu have no public carbon figures, so they use category medians per serving (beef 2.40, chicken 1.00, fish 0.80, plant-based 0.30, snacks 0.35 kg CO2e).
That means a UK measurement for a Big Mac may be applied conceptually to a Chinese supply chain it was not measured on, and a rare menu item gets a number from its category. The sensible reading is relative: beef-heavy orders beat chicken orders, delivery beats pickup, and the order of magnitude is plausible. Do not quote the ledger's total as a verified number. For a related look at how AI-assisted claims fare against evidence, see our claimed vs verified post on McDonald's AI pricing.
What the report and simulator show #
The HTML report includes a total footprint, an A to E grade, the layer breakdown, a monthly chart, your most carbon-heavy category and order, and equivalents such as trees and driving distance. The README uses a mature tree absorbing about 21 kg CO2 per year and a gasoline car emitting about 170 g per km for those conversions. It publishes no concrete sample totals in text, only an image of the report.
A green leaf bead moving along a track, illustrating a CO2e reduction simulator that swaps delivery for pickup
The reduction simulator models five changes and reports kg saved and percent of total:
- Swap red meat for white meat.
- Switch delivery to pickup.
- Reduce snacks.
- Halve desserts.
- Remove combo bundles.
The README says it only computes and does not moralize. Given the dish layer dominates, expect the beef swap to be the largest lever for most people, consistent with the README's own reasoning about beef's footprint.
How to try it #
Python 3.9 or newer is all you need.
PYTHONPATH=src python3 -m mccarbon demo
PYTHONPATH=src python3 -m mccarbon --mock --html carbon-book.html
For live data you need a token from McDonald's China's MCP platform. Verify it first with the account command, then generate the report with --live. Other subcommands are report (the default), export (normalized order JSON) and account, with options such as --start, --end, --name, --city, --json and --detail.
One packaging oddity: the clone instructions point to w16638771062/mccarbon, while the page we read is under yeqv111/mccarbon. Check which repository you are actually cloning before you run anything.
How does it compare with other ways to measure food emissions? #
Most consumer carbon calculators ask you to enter meals by hand and use generic national averages. mccarbon differs in three ways. It starts from real order history, so there is nothing to type. It separates packaging and delivery from the food itself, which many calculators ignore, and its README argues that this separation is why pickup looks so different from delivery. And it exposes its factor tables, so you can replace a median with a better number as soon as one is published.
The trade-off is precision. A life-cycle assessment of a single product measures a specific supply chain; a category median is a blunt average. If you need figures for reporting, use the tool to find which orders matter, then look for primary data on those items. For personal habit change, the relative ranking is usually enough: it tells you that a beef burger delivered in a plastic box costs far more carbon than a chicken wrap picked up in person, even if the exact kilograms are fuzzy.
Token safety: the part to take seriously #
Giving any tool a personal token is a trust decision, and food-order history reveals where you live, when you are home and what you eat.
- Prefer the environment variable. The README offers
MCD_MCP_TOKENor--token. A flag on the command line can remain in shell history, so use the variable. - Read the code first. The repository has no third-party dependencies, which makes a quick audit practical.
- Verify before use. The
accountcommand prints membership number and points; a401means the token is invalid or expired. - Keep the report private. The HTML is self-contained and masks card numbers by default, but order times and locations may still be inferable from it.
- Rotate if in doubt. If you pasted the token anywhere public, replace it.
If you let AI agents use MCP tokens like this, one more layer helps: AgentBeam, from the explainx.ai team, is an agent security platform that stops AI agents before they take dangerous actions, such as sending a credential somewhere it should not go.
Why it is trending, and why it is a useful template #
Our earlier post on mcd-saver-strategist covered the same contest ecosystem: McDonald's China exposing menus, coupons and order history through MCP has given hobbyists a real, consented data source. The two projects take opposite angles. One minimizes your bill; this one reports your emissions.
Lessons for builders:
- Make factors data, not code. Putting emission factors in tables you can audit is what turns a toy into something you can argue with.
- Ship an offline demo. Sample data lets people evaluate without credentials, which also cuts the security risk of trying a new tool.
- Label estimate quality. Saying which values are measured and which are medians is rarer than it should be.
- Keep dependencies at zero. For anything that touches personal tokens, a tiny auditable surface is a feature. Ourguide to MCP explains why connectors like this are spreading.
Limitations to remember #
- Order history only reflects what you bought, not what you wasted.
- The packaging and delivery numbers are averages and do not know your actual bag, box or rider.
- Regional and supply-chain variation is not modeled beyond category medians.
- The project is four commits old; expect factor changes and bugs.
- It is China-specific: the MCP server and menu are McDonald's China's.
Bottom line #
mccarbon is a well-scoped weekend project that shows how MCP can turn a company's consumer data into a personal analytics tool. Run the demo, read factors.py, and treat the numbers as directional. If you go live, guard the token the way you would a password.
Related reading #
Repository details (stars, forks, commits) are as of October 24, 2026 and change quickly.