MacroFactor MCP

A personal Model Context Protocol server that lets Claude.ai read your MacroFactor nutrition data and log food back into MacroFactor.

MacroFactor has no public API, so this uses only official mechanisms:

• Reads come from MacroFactor's built‑in Data Export (.xlsx), parsed locally and uploaded to the server.
• Writes (logging food) go through MacroFactor's official Apple Shortcuts Log by JSON action on your iPhone, triggered via a notification you tap to confirm.

No reverse‑engineering, no private API — so no meaningful ToS/ban risk (see "Risk").

Architecture

        reads                                   writes
  ┌──────────────┐   export.xlsx   ┌─────────────────────┐   /mcp    ┌──────────┐
  │ MacroFactor  │ ──────────────▶ │ scripts/ingest.mjs  │           │ Claude.ai│
  │   app (iOS)  │   (manual)      │ (local parse+upload)│           │   web    │
  └──────────────┘                 └──────────┬──────────┘           └────┬─────┘
        ▲                                      │ /ingest                   │ tool calls
        │ Log by JSON (tap)                    ▼                           ▼
  ┌─────┴────────┐   push    ┌────────────────────────────────────────────────┐
  │ iPhone       │ ◀──────── │  Cloudflare Worker (this repo)                   │
  │ Shortcut     │  Pushcut  │  • /mcp   authless MCP (read & log tools)        │
  └──────────────┘           │  • /upload-export  parses an export, refreshes D1│
                             │  • /today  live today feed from the phone        │
                             │  • /pending(-water) queues for iPhone Shortcut   │
                             └────────────────────────────────────────────────┘

Tools exposed to Claude

Tool	What it does
get_daily_nutrition	Daily calories / protein / carbs / fat / expenditure / weight / steps
get_micronutrients	Daily micros — fiber, sugars, sodium, vitamins, minerals, amino acids
get_food_log	Individual foods you ate, with time + macros (meal‑by‑meal); includes alcohol field, suspect flag for entries that may be inaccurate, and optional detail parameter for extended nutrient columns
get_weight_history	Scale weight (kg and lbs), trend weight, body‑fat %
get_expenditure	MacroFactor's calculated TDEE vs intake
get_steps	Daily step count
search_my_foods	Your Favorites / Custom Foods / history, with per‑serving macros
data_status	How fresh the loaded data is (incl. the live "today" feed)
get_today	Today's running totals live from your phone (no export needed) — consumed, micros, targets, what's left, freshness
get_targets	Calorie/macro targets for a date (resolves weekday cycling) + weight‑goal progress; week:true returns all 7 weekday rows of the governing program
get_goal_history	Every weight goal ever set, with planned (rate, ETA) vs actual (trend change, duration, realized rate) per goal
get_adherence	Per‑day intake vs target — hit‑rate, surplus/deficit, avg carb/fat gap vs target, true energy balance, est. kg change
weekly_summary	ONE digest over rolling 7/14/28‑day windows — avg calories/macros, adherence (incl. carb/fat gap), trend‑weight rate, TDEE drift, training volume, recent PRs
weekly_review	The whole weekly check-in in one call: weekly_summary + get_pr_alerts + day_of_week_patterns, sharing one end date
get_training_volume	Working sets + tonnage per muscle group over a range
get_exercise_progress	MacroFactor's per‑exercise metrics over time (1RM/3RM/10RM, heaviest, volume, reps, sets)
get_workouts	Logged sessions with per‑exercise sets (weight × reps × RIR), duration, top set; timed/distance/assisted sets carry duration/distance/base-weight fields
get_prs	Personal records per exercise — estimated 1RM (Epley), heaviest weight, best‑set volume; duration/distance bests for timed exercises
get_body_metrics	Body measurements (cm) + visual body‑fat assessment over time
get_program	Your planned training program — cycles, workouts, each exercise's planned sets (type, rep range, RIR, rest) + rest days
forecast_weight	When you'll hit goal weight — OLS trend regression and a calorie-math ETA; their divergence flags TDEE miscalibration. Optional target_date → required daily deficit
reconcile_energy_balance	Your implied maintenance calories (from weight delta + intake) vs MacroFactor's TDEE — catches under/over-logging
day_of_week_patterns	Per-weekday averages + each weekday's share of your weekly surplus — pinpoints the single highest-leverage day
get_nutrient_timing	Food log bucketed by time of day (fasted/morning/midday/afternoon/evening/late) — reveals protein distribution
detect_stall	Plateau vs metabolic adaptation vs intake-drift classifier with an adaptation_kcal estimate
micro_gap_analysis	28-day micronutrient averages vs NIH RDAs → ranked deficiency list (real export columns)
get_training_day_nutrition	Nutrition grouped by training-load tier (rest/light/moderate/heavy) — do you eat more on heavy days?
get_pr_alerts	Lifts that hit a new all-time PR (e1RM / heaviest / best-set volume / duration / distance), detected automatically on each export; includes the live front-squat:back-squat e1RM ratio (bottleneck_kpi)
log_food	Send a food to your phone to log in MacroFactor — optional intended_time records when you ate it and matches against the Food Log CSV on the next export import
log_saved_food	Log one of your saved Favorites/Custom foods by name × servings — scales the food's stored macros; disambiguates when the name matches more than one; accepts intended_time
log_water	Log water (mL) via MacroFactor's dedicated Log Water action on your phone
log_weight	Log a body weight (kg or lbs) via MacroFactor's dedicated Log Weight action on your phone
log_recipe	Log a named multi-ingredient meal — sums macros, attaches a recipe[] breakdown (reuses the food push); accepts intended_time
relog_meal	Re-log a past day's meal (optional hour window) as one entry — "log yesterday's lunch" in one tap; accepts intended_time
log_foods_batch	Log up to 20 foods in a single phone tap — ideal for a full meal or photo-estimated intake; each item accepts intended_time
cancel_pending_log	Delete queued-but-not-yet-tapped food/water/weight/batch logs ("never mind")
get_day	Full picture of a single day — nutrition totals, food log entries, body weight, and workout in one call
get_pending_logs	Queued (not-yet-tapped) food dispatches and recent dispatch history with landed status — see whether Claude's log reached MacroFactor

Proactive: when you upload an export (and once daily via cron), the server checks your lift log for new personal records and fires a Pushcut "New PR" push (set PUSHCUT_PR_WEBHOOK_URL); tap it and ask Claude get_pr_alerts for specifics.

Write-path audit log: every food dispatch is recorded in food_dispatch_log (queued, landed, or cancelled); optional intended_time on all five food-write tools is stored in food_intent_log and matched against the Food Log CSV on the next export import. When Shortcut 2 runs after a tap, it POSTs ?ack_id=N to /today, which simultaneously marks the dispatch landed in the audit log and refreshes live today data.

Three exports, all sent to the same /upload-export endpoint (auto‑detected by content): the .xlsx workbook (daily totals, all micronutrients, saved‑food library, nutrition targets + weight goals, body measurements + visual body‑fat, your planned training program, and MacroFactor's per‑muscle / per‑exercise training aggregates); the Food Log .csv (every item you ate, with time + macros); and the Workout Log .csv (every set: weight, reps, RIR). Upload any subset — each refreshes only its own tables.

Strength numbers: get_prs and get_workouts report the barbell load from your logged sets. get_exercise_progress and get_training_volume mirror MacroFactor's own figures, which (a) include bodyweight contribution for compound lifts — so a 100 kg front squat can show as ~160 kg — and (b) for per-muscle volume, credit each exercise to every muscle it trains, so per-muscle tonnage overlaps and sums to more than the session's bar tonnage. All correct; they just measure different things (bar load vs. training stimulus).

Prerequisites

• Node.js ≥ 22 (Wrangler requires it — you're warned if not). Use nvm/volta or the official installer.
• A free Cloudflare account.
• The MacroFactor iOS app (for the optional logging path).

Setup

1. Install + log in

npm install
npx wrangler login

2. Create the database

npx wrangler d1 create macrofactor

Copy the printed database_id into wrangler.jsonc (replace REPLACE_WITH_YOUR_D1_DATABASE_ID), then create the tables:

npm run db:init

3. Set the secrets

npx wrangler secret put INGEST_SECRET   # pick any strong random string
npx wrangler secret put MCP_TOKEN       # recommended — protects the MCP endpoint (see step 6)

4. Deploy

npm run deploy

Note the URL it prints, e.g. https://macrofactor-mcp.<you>.workers.dev.

5. Load your data

1. In MacroFactor: More → Data Management → Data Export → run the export and get the .xlsx onto this PC (AirDrop/iCloud/email). One file is all you need.
2. cp ingest.config.example.json ingest.config.json and fill in your Worker URL + the INGEST_SECRET you chose.
3. Upload (pass any subset of the three exports):

   npm run ingest -- "C:\path\to\workbook.xlsx" "C:\path\to\foodlog.csv" "C:\path\to\workoutlog.csv"
   

   Re‑run any time you export fresh data (each file replaces only its own tables).

6. Connect to Claude.ai

Claude.ai → Settings → Connectors → Add custom connector:

• URL: https://macrofactor-mcp.<you>.workers.dev/mcp/<MCP_TOKEN>
• Authentication: None (the secret token in the URL is the auth)

If you skipped MCP_TOKEN the URL is plain /mcp — not recommended: without a token, anyone who learns your Worker URL can read your nutrition/health data and queue food logs to your phone. Treat the full connector URL as a secret either way.

Ask things like "what was my protein this week?" or "how does my intake compare to my expenditure this month?"

7. (Optional) Log food via Claude

See ios-setup.md to wire up Pushcut + the iPhone Shortcut, then:

npx wrangler secret put PUSHCUT_WEBHOOK_URL

log_saved_food, log_recipe, and relog_meal reuse this same path (no extra setup). To also log water via Claude (log_water), add the small "MF Log Water" shortcut + its own Pushcut notification (see ios-setup.md), then:

npx wrangler secret put PUSHCUT_WATER_WEBHOOK_URL

log_weight and log_foods_batch each need their own small shortcut + Pushcut notification (see ios-setup.md), then their own webhook secret:

npx wrangler secret put PUSHCUT_WEIGHT_WEBHOOK_URL   # for log_weight
npx wrangler secret put PUSHCUT_BATCH_WEBHOOK_URL    # for log_foods_batch

For proactive PR alerts, create a Pushcut "New PR" notification and set its webhook:

npx wrangler secret put PUSHCUT_PR_WEBHOOK_URL

Risk

• Data export → reads: clean. Your own data via a feature built for it.
• Apple Shortcuts → writes: low risk. MacroFactor publishes the Shortcuts integration and endorses LLM‑driven Log by JSON; the write path requires a physical tap.
• We avoid the private Firestore API (App Check–blocked since ~May 2026, and a ToS breach).
• Optional: email support@macrofactor.com to confirm automation use in writing.

Known limits

• Food-write tools log at the tap time — MacroFactor's Log by JSON action uses the current time when the Shortcut runs. Pass intended_time to any food-write tool to store your intended eat-time server-side; it is matched against the Food Log CSV on the next import.
• Reads are as fresh as your last export/upload. Refresh from your phone with the "Update MF" Shortcut (POSTs the export to /upload-export) or from a PC with npm run ingest — see ios-setup.md.
• get_food_log needs the Food Log CSV and the training tools need the Workout Log CSV; the .xlsx workbook gives daily totals + micros + saved foods + targets + body metrics + planned training program + per‑muscle/per‑exercise training aggregates.
• get_exercise_progress for 1RM/3RM/10RM only returns data once MacroFactor has computed those estimates (needs a few logged sessions); until then use get_prs or the heaviest_weight / total_volume metrics.
• Weights are in kg (MacroFactor exports normalise to kg even if your app shows pounds).

Make it yours

Three constants encode preferences you'll want to adjust:

• Timezone — USER_TZ in src/db/utils.ts decides what "today" means (defaults to UTC). Set it to your IANA timezone (e.g. America/New_York) or post-midnight /today updates can land on the wrong day.
• Bottleneck KPI — squatBottleneck() in src/db/prs.ts tracks a front-squat : back-squat e1RM ratio surfaced by get_pr_alerts / weekly_review. Swap the exercise pair for your own, or ignore it — it returns null when either lift is absent.
• Micronutrient RDAs — MICRO_RDA in src/db/analytics.ts uses NIH DRI values for an adult male 19–50. Adjust the table for your demographic.

License

MIT — see LICENSE.