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. setup_complete is false until the account finishes its short setup; then setup_url is a link for the user to finish it on the website. Français (Canada) : Consulter le profil, la langue, les unités et les objectifs actuels.

update_goals

Change fixed daily goals with daily_calories or goals. Optional start_date/end_date schedule a temporary change, then baseline resumes. cancel_schedule_id removes one schedule. Legacy parameters remain supported: 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. Français (Canada) : Modifier les objectifs demandés en conservant leurs dates et leurs limites.

update_profile

Change target weight, weekly pace, goal direction (lose | maintain | gain), timezone (IANA name like America/Chicago), units or preferred_locale (en-US = English (US), en-CA = English (Canada), fr-CA = French; null follows the app/browser). Only change language when asked. These are profile fields only: they do NOT change the daily calorie goal. To change calories, use update_goals with an exact daily_calories amount. Français (Canada) : Modifier uniquement les préférences demandées par la personne.

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. Français (Canada) : Consulter les séries, les badges obtenus et les prochains paliers.

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. Français (Canada) : Chercher des aliments du catalogue. Conserver leurs noms, marques et valeurs nutritives.

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. Français (Canada) : Consulter les portions et les valeurs nutritives publiées d’un aliment.

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. Français (Canada) : Chercher le produit correspondant au code-barres, sans inventer de correspondance.

search_restaurants

The restaurant chains Simple Macros has full menus and customization nutrition for, with estimates labeled, limited to chains with locations in the user's country. 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. Français (Canada) : Chercher les chaînes offertes dans le pays de la personne.

get_restaurant_menu

A chain's menu with complete recorded nutrition and per-nutrient source quality: calories, protein, carbs, fat, fiber, sugars, sodium, cholesterol, saturated/trans fat and added sugars. Null means unknown; unverified means legacy values without source verification. Filter with query (fuzzy item name) or category. Set include_options to see option groups with all nutrient changes (included automatically when 5 or fewer items match). Follow each item's next_option_cursor using restaurant and option_cursor for all remaining options. Use build_menu_order for size-dependent and combined option math. Follow next_cursor until has_more is false. To log an item, pass { kind: 'menu_item', restaurant, menu_item_id, options?, remove_options?, quantity } to log_meal. Français (Canada) : Consulter le menu du pays, ses choix et ses valeurs nutritives. Suivre next_cursor si nécessaire.

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 calorie target is what the user has LEFT today, 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. For '800 calories of my macros at Taco Bell', pass restaurant and calories:800 ONLY. For 'Cava with my remaining calories', pass restaurant ONLY. Do not calculate or supply nutrient_constraints from daily goals: the server applies them. Daily nutrient bounds, including protein, always scale to this meal's calorie share, even when calories defaults to the remaining budget. Maximums are capped by what's left today. Only use remaining protein when the user explicitly asks for it: read get_day and pass that amount as protein_g. target.goal_allocation explains daily bounds, per-100-calorie ratios, logged amounts and applied whole-meal bounds; use target.nutrient_constraints as authoritative. ignore_daily_goals skips selected goals for this request only. must_include / exclude to steer it. Each idea has a combo_id: log it with log_meal items [{ kind: 'combo', combo_id }]. Every item carries full nutrition, source quality and breakdown_per_item (base plus options). nutrient_constraints are hard bounds; unknown or unverified values never qualify. The breakdown shows how a total is built from the chain's own portion sizes (a side cup is a different portion from an entrée portion). Français (Canada) : Trouver des commandes qui respectent le budget et les objectifs. Les estimations et les limites restent indiquées.

build_menu_order

Calculate calories and macros for a specific restaurant 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, all 11 supported nutrients, per-nutrient quality and order totals. Null means unknown. Log the same lines with log_meal as { kind: 'menu_item', restaurant, ...line }. Français (Canada) : Calculer les valeurs nutritives des articles et options choisis, sans les enregistrer.

find_nearby_restaurants

Stores near a place for the chains Simple Macros has menus for in the user's country, nearest first. Pass near (a city, ZIP or postal code, or address the user gave); without it, the client's approximate location is used when it shares one. Optionally restaurant to find one chain. Distances are in the user's unit (distance_unit: miles in the US and UK, km elsewhere). Then use get_restaurant_meal_ideas for what to order. Français (Canada) : Trouver des établissements dans le pays sélectionné, près de l’emplacement fourni.

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: search_foods first for any single food or product. 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. One that only resembles catalog foods is logged, and the result lists them in catalog_suggestions so you can offer to swap (update_meal). 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. Français (Canada) : Enregistrer les aliments et quantités demandés, avec leurs valeurs nutritives.

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. Français (Canada) : Modifier uniquement les articles, quantités, dates ou heures demandés.

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. Français (Canada) : Demander la confirmation avant d’appeler avec confirm: true.

log_weight

Log OR correct the day's weigh-in, in the chosen unit (default: the user's preference). 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. Français (Canada) : Enregistrer ou corriger la pesée du jour dans l’unité choisie. Il y a une seule pesée par date.

delete_weight

Delete the weigh-in for a date. Ask the user first, then call with confirm: true (without it nothing is deleted). Français (Canada) : Demander la confirmation avant de supprimer la pesée de la date.

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. Français (Canada) : Consulter les repas favoris et suivre next_cursor si nécessaire.

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. Français (Canada) : Consulter les ingrédients et les valeurs de la recette entière. Diviser par servings pour une portion.

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: search_foods first for any single food or product. 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. One that only resembles catalog foods is logged, and the result lists them in catalog_suggestions so you can offer to swap (update_meal). Restaurant food can't be a custom item: use menu_item or combo. Français (Canada) : Enregistrer un repas réutilisable avec son nom et ses portions.

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. Français (Canada) : Modifier le favori demandé, sans changer les repas déjà enregistrés.

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'. Français (Canada) : Créer une copie indépendante du favori.

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. Français (Canada) : Demander la confirmation avant de supprimer le favori. Les repas déjà enregistrés restent intacts.

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. `details` is what the team uses to find and fix the problem, so make it specific: what the user asked for, which tools you called with the inputs you sent and what came back (the numbers, names, dates and any error text), and what was wrong or what the user expected instead. We add the account, the assistant and our recent tool-call log ourselves. The team replies to the user by email. Français (Canada) : Avec l’accord de la personne, transmettre le problème précis à l’équipe Simple Macros.

propose_client_goals

Propose fixed daily goals to an active client by relationship_id. Does not change goals until the client explicitly accepts. Optional start_date and end_date are inclusive in the client timezone. Uses the same minimum, maximum, target and range rules as personal goals. Français (Canada) : Envoyer une proposition au client. Ses objectifs ne changent qu’après son acceptation.

list_my_clients

List only the signed-in coach's connected clients: names, connection status, organization name when applicable and the relationship reference used to select a client. Includes active clients and pending requests. No fitness records or check-in assessments are returned. Use get_client_days for an active client's records. Access is checked on every request. Français (Canada) : Consulter uniquement les clients accessibles au coach connecté.

get_client_days

Read one active client's records for a date range: logged meals with every food and its recorded nutrients, stored steps, weigh-ins, water entries and daily goals. Resolve client only among the coach's authorized relationships. Dates use the client's timezone; default today. Select only the needed categories with include. Returns dated records, not averages, trends, adherence scores or comparisons. Calculate those from the returned records, using the correct denominator. Never treat null steps or null water as zero or an empty meal log as zero food intake. Today is marked partial. Workouts are device-only and unavailable here. Follow next_start until has_more is false before describing the whole range. Client sharing consent includes connected AI assistants. Tracked fitness data is returned only for active relationships that authorize the signed-in coach or organization admin. Clients can revoke sharing in Settings, and permissions are checked on every request. Results are tracking summaries, not medical diagnoses or treatment recommendations. Français (Canada) : Consulter les catégories demandées pour un client autorisé. Utiliser son fuseau horaire et les unités du coach.

get_coach_invite_link

The coach's code and permanent link to send a client (the client opens it, installs Simple Macros and approves sharing), plus email invites nobody has accepted yet. For each organization they belong to, also their org code and link: a client who uses it joins the org and is assigned to this coach. Use for 'what's my coach code?', 'send me my link' and 'did Tammy accept my invite?'. The QR code is on simplemacros.com/coach/invite. To change the personal code use set_coach_code. Français (Canada) : Consulter le code, le lien et les invitations du coach. Le client doit approuver le partage.

set_coach_code

Change the coach's code (and so their link). Either a code they choose, 3 to 12 letters and numbers such as their name (SARAHLEE): spaces and dashes are dropped and it's saved in capitals, and the old code keeps working so links and QR codes already handed out still reach this coach. Or `random: true` for a new random code, for when a code was shared somewhere it shouldn't be: then the current code AND every old one stop working, so confirm with the coach first. Up to 5 code changes a day. Français (Canada) : Modifier le code du coach, en conservant les anciens codes comme indiqué dans la réponse.

resend_client_invite

Resend an open Simple Macros coaching invite identified by its email address or invite_id from get_coach_invite_link. Emails the recipient a fresh link valid for 14 more days, invalidates the old link, and revives an expired invite. Only invites sent by this coach can be resent. Confirm with the coach before sending. Français (Canada) : Renvoyer l’invitation demandée. Vérifier emailed avant d’annoncer l’envoi d’un courriel.

cancel_client_invite

Cancel an open Simple Macros coaching invite identified by its email address or invite_id from get_coach_invite_link. Invalidates its link in Simple Macros without sending an email. Only invites sent by this coach can be canceled. Confirm with the coach before canceling. Français (Canada) : Annuler le lien d’invitation demandé.

update_coach_profile

Read or change the signed-in coach's profile stored in Simple Macros: name, business, headline (80 characters max), specialties (up to 5 of: Weight loss, Muscle gain, Strength, Endurance, Sports performance, General health, Plant-based, Women's health, Men's health, Over 50, Bodybuilding, Habit coaching, Postpartum), how they coach (online, in person or both), city/region/country, languages, a price note, website, Instagram and TikTok usernames, and whether they're taking new clients. Only updates this coach's Simple Macros profile. Website and social usernames are stored as profile text; no websites or social accounts are contacted or edited. Only the fields passed change; call with no fields to read the profile. Show the coach the new text before saving. The photo is changed on simplemacros.com/coach/settings. Français (Canada) : Modifier uniquement les champs demandés du profil de coach.

remove_client

End coaching with a client, or decline one who is waiting for a seat. The coach stops seeing their data right away and the seat frees up. An active client gets a notice. This is the only way to free a seat; to come back, the client reconnects with the coach's code and approves sharing again. An organization client leaves the whole organization, and only an owner or admin can remove them (to move them to another coach, use assign_client). Confirm with the coach first. Français (Canada) : Retirer la relation demandée selon les confirmations requises.

approve_pending_client

Let a client who is waiting (pending_coach) in. While coaching is free nobody new waits, since there are no client limits; this is for an older request. If a plan limit is ever back on and the plan is full, the coach frees a seat by removing a client (remove_client). Only an owner or admin can approve an organization client. Français (Canada) : Approuver la demande de connexion du client.

invite_client_by_email

Email someone a one-time invite to connect with the coach in Simple Macros (the same invite the portal sends; it expires in 14 days). Whoever accepts it and approves sharing becomes the client. With `organization`, the client joins that organization instead: a plain org coach's invite assigns the client to themselves; an owner or admin may pick a coach with `assign_to` (or leave the client unassigned). Confirm the address with the coach first. Français (Canada) : Créer une invitation pour l’adresse demandée. Vérifier emailed avant d’annoncer l’envoi d’un courriel.

list_my_reviews

Reviews clients left for the coach, newest first, with the coach's reply if any, plus the average rating. Français (Canada) : Consulter les notes et avis du coach. Conserver les textes des auteurs.

respond_to_review

Post or replace the coach's one public reply to a client review stored in Simple Macros. Only updates reviews of this signed-in coach within Simple Macros; it does not contact external review platforms. The reply is displayed on the coach's Simple Macros profile. An empty response removes the reply. It replaces any earlier reply, so confirm the wording with the coach first. Français (Canada) : Publier ou retirer la réponse du coach à l’avis demandé.

get_coaching_plan

Read the signed-in coach's current client capacity: active and pending client counts, configured limits, remaining capacity, and whether client detail access is restricted by capacity. Also returns their coaching organizations and membership roles; organization capacity is available only to owners and admins. Null limits mean no configured limit. Does not change account access or client assignments. Français (Canada) : Consulter les limites de clients et les organisations accessibles.

get_goals

Read fixed daily goals, exact bounds, scheduled changes, revision, and pending coach proposals. Dates are inclusive local dates. Steps and water always use a minimum. Water amounts are in milliliters. Net carbs means total carbs minus fiber. Empty or incomplete tracking cannot establish that a maximum was met. Français (Canada) : Consulter les objectifs, leurs dates et les propositions en attente.

respond_goal_proposal

Accept or decline one pending coach proposal only after the user explicitly chooses. Read get_goals first and show the changes and dates. Acceptance updates only proposed metrics and requires the current revision. Français (Canada) : Accepter ou refuser une proposition d’objectifs du coach.

get_days

Read the signed-in user's own records for a date range: logged meals with every food and its recorded nutrients, stored steps, weigh-ins, water entries and daily goals. Use days or start/end in their timezone; default today. Select only the needed categories with include. Returns dated records, not averages, trends, adherence scores or comparisons. Calculate those from the returned records, using the correct denominator. Never treat null steps or null water as zero or an empty meal log as zero food intake. Today is marked partial. Workouts are device-only and unavailable here. Follow next_start until has_more is false before describing the whole range. Français (Canada) : Consulter les repas, pas, pesées, l’eau et les objectifs des dates demandées. Suivre next_start lorsque has_more est vrai.

log_water

Add one water entry. A day can have many; each call adds to the day's total, so log only what the user just drank and never resend the total. Convert what they said yourself (1 cup = 8 fl oz, 1 liter = 1000 mL) and ask when a size is unknown. Defaults to today and now. Français (Canada) : Ajouter une entrée d’eau. Chaque appel s’ajoute au total de la journée.

update_water

Change one water entry's amount, date or time. Only what you pass changes. Find water_log_id with get_days (include: ['water']). Français (Canada) : Modifier la quantité, la date ou l’heure demandée d’une entrée d’eau.

delete_water

Delete one water entry. Ask the user first, then call with confirm: true (without it nothing is deleted). Find water_log_id with get_days (include: ['water']). Français (Canada) : Demander la confirmation avant de supprimer l’entrée d’eau.