Simple Macros MCP reference

get_profile

The user's profile and today's goals: calories, protein, steps, goal direction and pace, activity level, current/target weight, TDEE, timezone, and this connection's access level.

update_goals

Change the user's daily goals from today on: calorie_diff (calories per day vs maintenance/TDEE, negative = deficit, e.g. -500), daily_protein_goal (grams), step_goal, activity_level. Returns the new goals and the TDEE math behind them. Past days keep their old goals.

update_profile

Change target weight, weekly pace, goal direction (lose | maintain | gain), or timezone (IANA name like America/Chicago). These are profile fields only: they do NOT change the daily calorie goal. To change calories, use update_goals (e.g. calorie_diff -500 for about 1 lb/week).

get_day

One day as the Simple Macros Track tab shows it: goals, totals, REMAINING calories and protein, every meal with its items (name, amount, calories, protein, carbs, fat, restaurant, favorite), steps, weigh-in, and streaks. Defaults to today. Use it for 'how many calories do I have left'.

get_history

One compact row per day for up to 92 days: calories and protein vs goals with pass flags (a calorie day passes within ±500 of goal), steps vs goal, weigh-in, meal count, and nutrient totals (carbs, fat, fiber, sugars, sodium, cholesterol). Plus period averages over logged days and adherence %. Give `days` (default 30) or `start`/`end`.

get_meals

Logged meals with their items, newest first, paginated. Filter by date range (up to 92 days, default last 30), restaurant_slug, or a text query matched against item names, brands and restaurant. Use it to find a meal to edit or to see what the user usually eats.

get_nutrient_report

Nutrients over the last N days (default 30, max 92), computed from itemized foods: per nutrient, the average per LOGGED day vs the daily value (scaled to the user's calorie goal; sodium and cholesterol are fixed limits), % of logged days meeting it (under the limit for fat/sugars/sodium/cholesterol, at or over for carbs/fiber), coverage (% of logged items that carried the field, so a low number means 'we don't know' rather than 'you ate none'), and the top 10 contributing foods. Use for 'what am I missing' and 'where is my sodium coming from'.

get_frequent_foods

The foods, restaurants and favorites the user logs most over the last N days (default 30, max 92), with the most recent amount and macros for each food. Start swap suggestions and 'my usual' lookups here: a frequent food can be re-logged as a custom item with the same macros, or via its food_item_id when it has one.

get_streaks_and_badges

Current and longest streak for weigh-ins, calorie goal (within ±500), protein goal and steps; every badge earned with its date; and the next badge in each category with how far away it is when we can tell. Badges are awarded by the app, so a badge earned from here shows up after the app next opens.

get_weight_history

Weigh-ins over the last N days (default 90, max 730), one per day, with a 7-day moving average, change over the period, and change since the starting weight.

search_foods

Search the Simple Macros food catalog (USDA whole foods, packaged/branded products, and community-scanned items) for 1 to 10 foods at once. Returns candidates per query with food_item_id, name, brand, default serving and per-serving calories/protein/carbs/fat. An empty list means we don't have it: then use a custom item. Log it with log_meal as { kind: 'food', food_item_id, quantity }. Check list_favorites and get_frequent_foods first for the user's own versions.

get_food

Full details of one catalog food by food_item_id: per-100g macros (calories, protein, carbs, fat, fiber, sugars, sodium, cholesterol), the default serving, and the 'as prepared' state when the label has one (e.g. dry pasta vs cooked). Needed to log by weight ('150 g') or as prepared.

lookup_barcode

Find a packaged product in our catalog by its UPC/EAN barcode. Several candidates can share a barcode; they come ranked with verified ones first. No match means we don't have it yet (adding a product needs the app's label-photo flow), so tell the user and use a custom item if they want it logged. Log it with log_meal as { kind: 'food', food_item_id, quantity }. Check list_favorites and get_frequent_foods first for the user's own versions.

search_restaurants

The restaurant chains Simple Macros has full menus for (official nutrition, every option). Search by name, or omit query to list them all. Use the slug with get_restaurant_menu, get_restaurant_meal_ideas and log_meal. For stores near a place, use find_nearby_restaurants.

get_restaurant_menu

A chain's menu from Simple Macros with official macros: each item's default build and its calorie/protein range across options. Filter with query (fuzzy item name) or category. Set include_options to see every option group with each option's calorie/protein change (on automatically when 5 or fewer items match). To log an item, pass { kind: 'menu_item', restaurant, menu_item_id, options?, remove_options?, quantity } to log_meal.

get_restaurant_meal_ideas

Simple Macros' Meal Generator: real orders at a chain that hit a calorie target with at least a protein floor, built from the official menu. With no calories, the target is what the user has LEFT today (calories and protein), so 'what can I eat at X to fill out my day' needs only the restaurant. With calories and no protein_g, the protein floor is that many calories' worth of their daily goals (the app's ratio), so '750 calories that hits my macros' needs only calories. Pass protein_g ONLY when the user is explicit (a number, or 'my remaining protein'); never fill it in yourself. must_include / exclude to steer it. Each idea has a combo_id: log it with log_meal items [{ kind: 'combo', combo_id }]. The numbers are the chain's official published nutrition, and every item carries breakdown_per_item (base plus each option). If a total looks off, show that breakdown; don't recompute it from outside figures or from a differently sized portion (a side cup is not an entrée portion).

build_menu_order

Work out the macros of a specific order before logging it: items by menu_item_id or name, with options to add/swap and default ingredients to remove. Returns each line's exact name and macros and the total. Log the same lines with log_meal as { kind: 'menu_item', restaurant, ...line }.

find_nearby_restaurants

Stores near a place for the chains Simple Macros has menus for, nearest first. Pass near (an address, city or ZIP) or latitude + longitude; optionally restaurant to find one chain. Then use get_restaurant_meal_ideas for what to order.

log_meal

Track one meal in Simple Macros; it shows on the Track tab like a meal logged in the app. Each item is one of: { kind: 'food', food_item_id, quantity, unit? } from our catalog; { kind: 'favorite', saved_meal_id, portions? } for a saved favorite; { kind: 'menu_item', restaurant, menu_item_id or name, options?, remove_options?, quantity? } for a restaurant item (get_restaurant_menu); { kind: 'combo', combo_id } for a whole idea from get_restaurant_meal_ideas; or { kind: 'custom', name, amount, unit, calories, protein_g, carbs_g?, fat_g?, ... } with macros for the WHOLE amount, only for recipes and foods search_foods doesn't have. A custom item that matches a catalog food is rejected with error_code 'resolvable' and candidates: resend with the food_item_id, or with allow_custom: true if it's genuinely different. Restaurant food can't be a custom item: use menu_item or combo. Optional date (YYYY-MM-DD, default today), time (HH:mm), and label. Returns the meal and what's left for the day.

update_meal

Edit a logged meal by meal_id (from get_day / get_meals): add_items, remove_food_ids (the item food_id values from get_day), set_quantity to change one item's amount, set_items to replace everything, or move it with date / time / label. Items use the same shapes as log_meal. Returns the updated meal and what's left for the day.

delete_meal

Delete a logged meal and all its items. Ask the user first, then call with confirm: true (without it nothing is deleted). Saved favorites are not affected.

log_weight

Log OR correct the day's weigh-in, in pounds. A day has exactly one weigh-in: if one already exists for that date it is updated (the result says updated: true and gives previous_weight_lb), never duplicated. Defaults to today and now.

delete_weight

Delete the weigh-in for a date. Ask the user first, then call with confirm: true (without it nothing is deleted).

list_favorites

The user's saved favorites (reusable meals and recipes), most-used first, with servings, per-serving calories/protein, tags, restaurant and item names. `query` matches names, items and restaurant fuzzily; `tag` filters (breakfast, lunch, dinner, snack, sides, drinks, restaurant). Check here first when the user says 'my usual' or names a meal.

get_favorite

One favorite with every item (item_id, name, amount, calories, protein, carbs, fat) for the WHOLE batch; divide by servings for one serving.

create_favorite

Save a reusable favorite. Give EITHER from_meal_id (copy a logged meal's items; that meal then shows as this favorite in the app) OR items[] (same shapes as log_meal). servings = how many servings the whole thing makes (default 1; a batch recipe might make 6). On a name clash you get error_code 'name_taken'; ask the user, then retry with replace_existing: true or a new name. Each item is one of: { kind: 'food', food_item_id, quantity, unit? } from our catalog; { kind: 'favorite', saved_meal_id, portions? } for a saved favorite; { kind: 'menu_item', restaurant, menu_item_id or name, options?, remove_options?, quantity? } for a restaurant item (get_restaurant_menu); { kind: 'combo', combo_id } for a whole idea from get_restaurant_meal_ideas; or { kind: 'custom', name, amount, unit, calories, protein_g, carbs_g?, fat_g?, ... } with macros for the WHOLE amount, only for recipes and foods search_foods doesn't have. A custom item that matches a catalog food is rejected with error_code 'resolvable' and candidates: resend with the food_item_id, or with allow_custom: true if it's genuinely different. Restaurant food can't be a custom item: use menu_item or combo.

update_favorite

Edit a favorite's template: rename, change servings or tags, add_items, remove_item_ids (item_id from get_favorite), or set_items to replace all. Future logs use the new version; meals already logged keep their copy.

duplicate_favorite

Copy a favorite into a new, independent one (named '<name> (copy)' unless you give a name). Useful for 'the same, but with one change'.

delete_favorite

Delete a favorite. Meals already logged with it keep their food (they hold their own copy). Ask the user first, then call with confirm: true.

report_issue

Send the Simple Macros team a problem report when something went wrong here: wrong or surprising numbers, a meal or weigh-in that didn't log right, a food or menu item we're missing, or an error message. Offer it when the user says something is broken or wrong, and ask before sending, because it includes part of this conversation. Put the relevant exchange in `conversation`: the user's messages and your tool calls with their inputs and results, verbatim where you can. We add the account, the assistant and our recent tool-call log ourselves. The team replies to the user by email.