Skip to main content
Glama

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-mcp

Export 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, daily_briefing, and weekly_report. Recovery output uses the nutrition signals that exist.

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 tools
analyze_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

    B3.4/5.0

    Scored across 29 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      MCP 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.
      35
      164 npm
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      1
      MIT