macrofactor-mcp
This server is a local Fueling & Recovery Decision Engine that combines MacroFactor nutrition data with optional Garmin training/health data, storing everything in a local DuckDB database. Here's what you can do:
Data Management
import_export— Import MacroFactor.xlsxexport filessync_garmin— Pull Garmin Connect data (daily stats, activities, sleep, training status, body fat)data_status/clear_data/setup_check— Manage and diagnose your local dataquery— Run custom read-only SQL queries across 20+ tables
Nutrition
get_nutrition_summary/get_nutrition_range— Daily or range-based nutrition breakdownsget_food_log/search_food— View and search logged foodsget_compliance_report— Compare actual intake vs. targetsanalyze_meal_patterns— Analyze meal timing, frequency, and foods correlated with hitting targets
Weight & Body Composition
get_weight_trend— Track weight over timedetect_phases— Auto-detect cut/bulk/maintenance phases from weight and energy balancebody_comp_trend— Track weight, body fat, training volume, and calorie balance over time (up to 90 days)
Workouts & Training
get_workout_log/get_workout_history— View workout details and historyget_muscle_group_summary— Sets and volume by muscle groupget_exercise_progress— Track 1RM, volume, and reps for specific exercises
Garmin Health Monitoring
garmin_status— Snapshot of Garmin stats, sleep, and training status for a given date
Flagship Cross-Domain Workflows
recovery_check— Readiness assessment combining sleep, HRV, body battery, training load, and yesterday's nutritiondaily_briefing— Full-day unified view of nutrition, adherence, body metrics, sleep, and trainingweekly_report— Comprehensive 7-day report to inform next-week adjustmentsnutrition_performance_correlation— Correlate protein/calorie intake with next-day HRV, sleep score, and body batterysleep_analysis— Analyze how prior-day training, calories, and meal timing affect sleep quality
Personalized Insights
get_insights— Cross-domain insights with trend alerts, personal correlations, and prioritized recommendationsget_digest— Comprehensive weekly/monthly digest covering nutrition, weight, training, and adherenceget_combined_data— Unified query merging nutrition + health data by date and domain
Retrieves Garmin training, sleep, HRV, body battery, and activity data to enhance fueling and recovery analysis with real-world performance metrics.
Am I recovered? Did my fueling work? What should change next week? The only MCP combining MacroFactor nutrition with Garmin training data.
MacroFactor MCP is a local Fueling & Recovery Decision Engine. Give your MCP client a MacroFactor export, optionally add Garmin, and ask for a decision instead of manually comparing nutrition, sleep, body, and training screens.
Quickstart
Install uv, then confirm the packaged server starts:
uvx macrofactor-mcpExport your data from MacroFactor, put the .xlsx file in one local directory,
and add this to your MCP client configuration. Use absolute paths.
{
"mcpServers": {
"macrofactor": {
"command": "uvx",
"args": ["macrofactor-mcp"],
"env": {
"MACROFACTOR_DATA_DIR": "/absolute/path/to/macrofactor-exports",
"MACROFACTOR_DB_PATH": "/absolute/path/to/macrofactor.duckdb"
}
}
}
}Restart the MCP client. The server imports new workbooks on startup. Run
setup_check, then ask one of the questions below. If a desktop client cannot
find uvx, replace "uvx" with the absolute path returned by which uvx.
Related MCP server: catence
Four flagship workflows
All examples below use synthetic data.
recovery_check — Am I recovered?
Combines last night's sleep, HRV, body battery, training load, and yesterday's fueling into a readiness view.
Recovery Check: 2026-07-08
Sleep: 7h 38m, score 82; HRV +4 vs 7-day average
Training load: ACWR 1.08 (optimal)
Yesterday: 96% calorie target; 101% protein target
Overall: All systems go — 4 positive signals.daily_briefing — What do today's signals say together?
Shows the day as one picture instead of separate nutrition and training logs.
Daily Briefing: 2026-07-08
Intake: 2,340 kcal (P 171g / F 72g / C 248g)
Adherence: 98% calories | 101% protein
Body Battery: 28 → 83 | Sleep: 7h 38m, score 82
Training: Productive | Load 612/568 (ACWR 1.08)weekly_report — What should change next week?
Reviews seven days of nutrition, weight, workouts, sleep, and training load.
Weekly Report: 2026-07-02 to 2026-07-08
Average: 2,315 kcal | 168g protein
On target: calories 6/7 days | protein 7/7 days
Training: 4 sessions | Sleep: 7h 26m average
Next-week signal: fueling was consistent; protect sleep before adding load.nutrition_performance_correlation — Did my fueling work?
Compares nutrition with next-day Garmin recovery signals. It reports sample sizes so small or missing datasets stay visible.
Nutrition → Performance Correlation: 28 paired days
Protein >=90% target: next-day HRV 51 vs 45 (+6)
Protein >=90% target: sleep score 81 vs 76 (+5)
Energy deficit days: body battery 68 vs 75 (-7)
Observation: higher-protein days tended to precede better recovery.MacroFactor-only or MacroFactor + Garmin
Mode | Decisions available |
MacroFactor only | Nutrition, weight, workouts, |
MacroFactor + Garmin | All four flagship workflows, including sleep, HRV, body battery, activities, and training load. |
Garmin is optional. To enable it, point GARMINTOKENS at an existing local
Garth/Garmin token directory, then run sync_garmin.
Platform support
macOS and Linux
Windows is untested
Python 3.10 or newer
Limitations
v0.1 requires a manual MacroFactor export; it does not connect to a MacroFactor API.
Garmin correlation workflows need overlapping MacroFactor and Garmin dates.
Correlations are observational, not proof that one behavior caused another outcome.
Import support follows the current MacroFactor Quick Export and All-Time Data workbook layouts.
Privacy
Raw nutrition, body, workout, and Garmin data stays in the local DuckDB database. The server does not upload that database. However, MCP tool results are sent to whatever model or client the server is connected to. Review that client's data policy and avoid requesting more detail than you want to share.
Disclaimer
This is an unofficial project. It is not affiliated with, endorsed by, or supported by MacroFactor or Stronger By Science. It is not medical advice and must not replace care from a qualified health professional.
Released under the MIT License.
mcp-name: io.github.NasserAlbusaidi/macrofactor-mcp
Available Tools
29 toolsanalyze_meal_patternsA
Analyze meal timing, frequency, and which foods correlate with hitting targets.
Shows when you eat, how many meals per day, most frequent foods, and which
foods appear most on days where you hit your calorie and protein targets.
Args:
start_date: Start date (YYYY-MM-DD). Default: 30 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
limit: Max foods to show per category (default 15).
Inputs: limit, end_date, start_date. Returns: result
body_comp_trendA
Track body composition over time — weight, body fat, training volume, energy balance.
Answers: am I gaining muscle or fat? Combines weight trend with body fat,
training volume, and calorie surplus/deficit.
Args:
start_date: Start date (YYYY-MM-DD). Default: 90 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
Inputs: end_date, start_date. Returns: result
clear_dataA
Clear all imported data so you can reimport fresh exports.
Inputs: no named parameters. Returns: result
daily_briefingA
Complete day view combining MacroFactor nutrition + Garmin health data.
The cross-data tool — shows nutrition, adherence, body, activity,
sleep, and training in one view. No API calls — reads from DuckDB.
Args:
date_str: Date in YYYY-MM-DD format. Empty = today.
Inputs: date_str. Returns: result
data_statusA
Check what data is currently loaded — date ranges, row counts, last import.
Inputs: no named parameters. Returns: result
detect_phasesA
Auto-detect cut/bulk/maintenance phases from weight trend and energy balance.
Analyzes the full history and identifies distinct phases based on trend weight
direction and caloric balance. Each phase shows duration, weight change, and
average deficit/surplus.
Args:
min_days: Minimum days for a phase to be reported (default 14).
Inputs: min_days. Returns: result
garmin_statusA
Quick Garmin health snapshot for a date. No API calls — reads from synced DuckDB data.
Combines daily stats, sleep, and training status in one view.
Run sync_garmin first to populate data.
Args:
date_str: Date in YYYY-MM-DD format. Empty = today.
Inputs: date_str. Returns: result
get_combined_dataA
Unified cross-domain query — returns merged nutrition + health data by date.
One call replaces multiple tool calls. Returns all requested domains in one payload.
Args:
start_date: Start date (YYYY-MM-DD). Default: 7 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
domains: List of domains to include. Options: nutrition, weight, sleep,
training, activity, workouts. Default: all.
Inputs: domains, end_date, start_date. Returns: result
get_compliance_reportB
Compare actual intake vs targets over a date range. Shows adherence.
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
Inputs: end_date (required), start_date (required). Returns: result
get_digestA
Get a comprehensive weekly or monthly digest combining nutrition, weight, training, and adherence.
One call instead of five — gives a complete picture of a period.
Args:
period: "week" (last 7 days) or "month" (last 30 days).
end_date: End date (YYYY-MM-DD). Default: today.
Inputs: period, end_date. Returns: result
get_exercise_progressB
Track progress for a specific exercise over time.
Args:
exercise: Exercise name (case-insensitive, partial match).
metric: One of: estimated_1rm, estimated_3rm, estimated_10rm,
total_volume, best_set_volume, heaviest_weight,
total_reps, best_set_reps, total_sets,
total_duration, best_set_duration,
total_distance, best_set_distance.
limit: Max data points to return (default 20, most recent).
Inputs: exercise (required), limit, metric. Returns: result
get_food_logA
Get all foods logged on a specific date.
Args:
date_str: Date (YYYY-MM-DD). Default: today.
Inputs: date_str. Returns: result
get_insightsA
Get personalized insights based on your nutrition, training, sleep, and recovery data.
Analyzes cross-domain patterns specific to YOUR data. Includes:
- Current state (phase, weight trajectory, weekly nutrition pacing)
- Trend alerts (sleep, HRV, body battery, compliance changes)
- Personal correlations (what actually affects YOUR recovery)
- Actionable recommendations prioritized by urgency
- Sparkline trends for key metrics
Works best with both MacroFactor and Garmin data synced.
No arguments needed — analyzes everything automatically.
Inputs: no named parameters. Returns: result
get_muscle_group_summaryB
Get muscle group sets and volume summary. Defaults to last 7 days.
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
Inputs: end_date, start_date. Returns: result
get_nutrition_rangeB
Get daily nutrition data for a date range.
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
Inputs: end_date (required), start_date (required). Returns: result
get_nutrition_summaryC
Get nutrition summary for a specific date.
Args:
date_str: Date in YYYY-MM-DD format. Empty = today.
Inputs: date_str. Returns: result
get_weight_trendB
Get weight trend data. Defaults to last 30 days.
Args:
start_date: Start date (YYYY-MM-DD). Default: 30 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
Inputs: end_date, start_date. Returns: result
get_workout_historyA
Get a summary of all workouts in a date range. Defaults to last 30 days.
Args:
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
Inputs: end_date, start_date. Returns: result
get_workout_logB
Get workout details for a specific date.
Args:
date_str: Date (YYYY-MM-DD). Default: most recent workout.
Inputs: date_str. Returns: result
import_exportA
Import a MacroFactor .xlsx export file into the database.
Supports both Quick Export and All-Time Data formats.
If filename is empty, auto-detects the most recent .xlsx in the data directory.
Args:
filename: Path to .xlsx file, or empty to auto-detect.
Inputs: filename. Returns: result
list_exercisesA
List all tracked exercises with available metrics.
Inputs: no named parameters. Returns: result
nutrition_performance_correlationA
Correlate nutrition intake with next-day training metrics.
Shows whether protein/calorie intake patterns affect next-day body battery,
HRV, and workout performance. Splits days into high/low intake buckets.
Args:
start_date: Start date (YYYY-MM-DD). Default: 30 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
Inputs: end_date, start_date. Returns: result
queryA
Run a custom SQL query against the MacroFactor database.
Available tables:
- daily: date, calories, macros, targets, weight, expenditure, steps, micros
- food_log: date, time, food details (from Quick Export)
- workouts: date, exercise, sets, reps, weight (from Quick Export)
- muscle_sets: date, muscle_group, sets
- muscle_volume: date, muscle_group, volume_kg
- exercise_tracking: date, exercise, metric, value (from All-Time)
- body_metrics: date, metric, value
- custom_foods: food_name, nutrition info
- nutrition_targets: program_date, weekday, targets
- food_log_notes: date, name, note
- garmin_daily_stats: date, steps, calories, HR, stress, body battery
- garmin_activities: activity_id, date, type, duration, distance, HR, power
- garmin_sleep: date, sleep phases, score, HRV, SpO2
- garmin_training_status: date, status, VO2max, training load, FTP
- garmin_body_fat: date, body_fat_pct
- garmin_sync_log: sync history
Use `data_status` to see what's loaded.
Args:
sql: SQL query (read-only SELECT statements only).
Inputs: sql (required). Returns: result
recovery_checkA
Readiness assessment — should you train hard today?
Combines last night's sleep, body battery, training load ratio,
and yesterday's nutrition compliance into a single readiness view.
Args:
date_str: Date to check (YYYY-MM-DD). Default: today.
Inputs: date_str. Returns: result
search_foodA
Search logged foods by name across all dates.
Also searches custom foods if no log results found.
Args:
query: Search term (case-insensitive).
limit: Max results (default 20).
Inputs: query (required), limit. Returns: result
setup_checkA
Check local setup and explain the easiest next action.
Use this first when the MCP seems empty, stale, misconfigured, or when you
are not sure which tool to call next.
Args:
show_workflows: Include common question-to-tool workflows.
Inputs: show_workflows. Returns: result
sleep_analysisA
Analyze what affects sleep quality — prior-day training, calories, timing.
Correlates sleep scores with training intensity, total calories, and meal
timing from the preceding day.
Args:
start_date: Start date (YYYY-MM-DD). Default: 30 days ago.
end_date: End date (YYYY-MM-DD). Default: today.
Inputs: end_date, start_date. Returns: result
sync_garminA
Sync Garmin health data into local DuckDB for fast cross-queries with MacroFactor data.
Pulls daily stats, activities, sleep, training status, and body fat
from Garmin Connect for the last N days. Data is upserted (idempotent).
Args:
days: Number of days to sync (default 7).
Inputs: days. Returns: result
weekly_reportA
Comprehensive 7-day report — nutrition, workouts, sleep, body, activity in one call.
Includes daily detail for weight and nutrition, full workout breakdown with
merged MacroFactor + Garmin strength data, sleep trends, and training load.
Args:
end_date: Last day of the week (YYYY-MM-DD). Default: today.
Inputs: end_date. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Several tools have overlapping purposes, such as multiple summary/report tools (daily_briefing, get_digest, weekly_report) and similar analytical tools (analyze_meal_patterns, sleep_analysis, nutrition_performance_correlation). Descriptions help differentiate, but an agent could easily select the wrong one.
Most tool names follow a verb_noun pattern in snake_case (e.g., get_food_log, sync_garmin). However, some names use noun_noun (body_comp_trend, nutrition_performance_correlation) or are ambiguous (query), introducing minor inconsistency.
With 29 tools, the server exceeds the 25-tool threshold for 'too many.' While the scope is broad (nutrition, fitness, Garmin data), many tools could be consolidated (e.g., multiple get_ tools) or are redundant given the SQL query tool.
The server covers the major domain areas well: nutrition tracking, body composition, workouts, Garmin health data, and cross-domain analytics. Minor gaps exist, such as no tool for setting goals or editing entries, but these are likely out of scope for a read-analysis toolset.
Maintenance
Related MCP Connectors
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
Fitness MCP for coaches and gyms: build workouts and read clients' training from live Superset data.
Apple Health training load, recovery, HRV and workout detail for Claude, ChatGPT and any MCP client.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal-first cycle coach MCP for phase-aware nutrition and training context.17110 npmMIT
- AlicenseBqualityBmaintenanceMCP server for local fitness-data extraction and analysis from Garmin Connect, Intervals.icu, and Strava. Provides read-only analytical tools over DuckDB and targeted Strava enrichment.35164 npm1AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceA local MCP server that exposes your Garmin Connect data—sleep, HRV, training readiness, workouts, and more—to any MCP-compatible AI assistant. Runs entirely on your machine and keeps your Garmin credentials private.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that mirrors your Garmin data into a personal database and exposes tools for health summaries, training load, muscle readiness, and race analysis, with optional chat-driven insights via stdio or HTTP.1MIT