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.

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, the day's running totals (calories, protein, carbs, fat, fiber, sugars, sodium, cholesterol) with nutrient_coverage_pct (share of the day's items that list each nutrient; under 100 means some foods don't publish it), 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' and 'how much sodium have I had today'.

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 a period (last N days, default 30, max 92; or start/end; or one `date`), 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). 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).

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 (a city, ZIP 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. 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. `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.

list_coaching_clients

The coach's clients: active and waiting for a seat (pending_coach), each with the relationship_id, connected date, today's calories and protein vs goal, 7-day adherence, days since the last log, latest weight, attention signal types and, for organization clients, the org and who they're assigned to. Filter with `filter` (default: everyone), `q` (a name) and `organization` ('personal' or one org). Waiting clients show only the name until they get a seat.

get_coaching_overview

The coach's dashboard: their plan (free right now, unlimited clients) and each organization they belong to, clients who need attention (with the evidence), who has and hasn't logged today, clients waiting for a seat, and recent weigh-ins. `organization` narrows it to 'personal' clients or one org. Start here for 'who needs my attention today' or 'how are my clients doing'.

get_clients_needing_attention

Every attention signal across the coach's clients, most urgent first, each with a plain-English message and its evidence numbers: waiting for a seat, nothing logged for a whole day (yesterday or longer), no weigh-in for 3+ days, over calories on 4+ of the last 7 days, protein under 80% of goal, steps under goal 3+ days in a row, logging down 30%+ vs the 2 weeks before, weight flat for 21 days on a lose/gain goal, and (with include_new) new clients.

get_client_day

One day of a client's log, meal by meal with every food and its macros, plus the day's goals, totals (calories, protein, carbs, fat, fiber, sugars, sodium, cholesterol), what's left, steps and weigh-in. Dates are the client's local date; defaults to their today.

get_client_summary

A client's last 7, 14, 30 or 90 COMPLETE days (ending yesterday in their timezone; today is partial and reported separately): days logged, averages over logged days (calories, protein, carbs, fat, steps), calorie adherence (within ±500 of each day's own goal), protein adherence (at or over), step adherence, weight (latest, 7-day average, change, trend lb/week), and with compare (default true) the previous equal period and the deltas. Report these numbers; don't recompute them.

get_client_weight_trend

A client's weigh-ins over the last N days (default 90, max 365) with the 7-day moving average, the change over the period, the trend in lb per week and their goal (direction, target weight).

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.

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.

manage_client_invite

Resend or cancel an email invite the coach sent that nobody has accepted yet (get_coach_invite_link lists them). Resend emails a fresh link, good for 14 more days, and the old link stops working; it also revives an expired invite. Cancel makes the link stop working. Identify the invite by the email it went to or its invite_id. Confirm with the coach before canceling.

update_coach_profile

Read or change the coach's public profile: name, business, headline, bio (300 characters max, first person), 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 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.

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.

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.

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.

list_my_reviews

Reviews clients left for the coach, newest first, with the coach's reply if any, plus the average rating.

respond_to_review

Post (or replace) the coach's one public reply to a review. An empty response removes the reply. It replaces any earlier reply, so confirm the wording with the coach first.

get_coaching_plan

The coach's plan. Simple Macros for Coaches is free right now (free_for_everyone: true): unlimited clients and coaches, nothing to buy, every limit null. Also returns active and waiting clients, any renewal or cancel date left from an earlier paid plan, and each organization they belong to (role, org code; for owners and admins also the org's clients and coaches). If free_for_everyone is ever false, it also shows the client limit, whether they're over it (and when client pages lock) and billing_url, where plans are changed. Plans are never bought or changed through an assistant.

get_team_overview

For an organization owner or admin: every coach in the org with their active clients and how many need attention, clients nobody is assigned to yet, clients waiting for a seat, attention signals across the whole org, the org's client seats (and lock) and coach seats. `organization` is optional when they manage exactly one. Use assign_client to assign or move clients.

assign_client

For an organization owner or admin: assign one of the org's clients to a coach in the org, or with `unassign: true` take a coach off them. `replace: true` makes that coach the only one (everyone else assigned to the client is removed), which is how to move a client to another coach. The client keeps sharing with the org either way; assigned coaches see the client, other plain coaches don't. Confirm with the coach before replacing.