io.github.endurancetools/garmin-mcp

Save a new structured workout to Garmin Connect (then use schedule_workouts to put it on the calendar so it syncs to the watch). Pass exactly one of: `preset` for a standard session from a few parameters (run_intervals, walk_run, easy_z2, strength_circuit); `definition` for anything else (typed steps with duration and target, nestable repeats); `garmin_json` only to copy an existing Garmin workout JSON. Errors name the bad field, e.g. steps[2].steps[0].target. Call with dry_run: true first, show the steps to the user and save only after they agree. dry_run saves nothing and does not contact Garmin: it returns the readable steps and the estimated duration (time steps, plus distance steps at the middle of their pace range; steps with neither are listed in estimate_note, and for garmin_json that carries its own estimate the note says it was taken from there).

Save an activity as a file on this machine and return its path: fit (original device file), gpx, tcx, kml or csv (laps). Use when the user wants the file itself, e.g. to import elsewhere.

Download data from Garmin Connect into the local cache. Read tools already download missing data by themselves, so call this only when the user asks to sync/refresh or to pre-load a range, or when a tool returned meta.sync_hint (auto fetch turned off) and the user agreed; pass the hint's scope/from/to. Days already stored are skipped. Long ranges run in the background in 7-day chunks with pauses and a daily request cap to stay gentle with Garmin; this waits at most 20 s and reports progress (also in garmin://sync-status). Example: {"scope":"health","from":"2026-09-01","to":"2026-09-30"}.

List workouts/activities (runs, rides, swims, strength...) as dense summaries: id, date, type, name, duration, distance, pace or speed, HR, training load. Use for "what did I do last week", finding an activity id, or comparing sessions. For one activity in depth use get_activity; for weekly/monthly totals use get_period_summary. Example: {"from":"2026-10-01","type":"running","limit":10}.

Details of one activity by id. detail="summary" (default) for the overview incl. description, RPE and feel; "splits" adds laps; "hr_zones" adds time in HR zones; "power_zones" adds time in power zones (power meter); "weather" adds temperature, wind and conditions during the activity; "exercise_sets" adds strength sets (exercise, reps, weight, rest); "full" adds all of these plus the raw second-by-second stream (HR, pace, GPS...) paginated with next_cursor, 50 KB per page - only when the user needs raw samples.

Weigh-ins (kg, body fat %, muscle mass, BMI) in a range with change and trend. Default range: last 90 days.

Garmin devices on the account with model, firmware, last sync time and settings (time/date format, units, tones, move and heart-rate alerts, pulse ox during sleep, number of alarms). Comes from the reference sync.

Shoes, bikes and other gear with total distance, usage since, notes and status. include_activities adds the last 10 activities per item.

Own transparent load model (TSS per activity from power, else pace, else heart rate, else session RPE, with date-dependent thresholds), not Garmin's EPOC load; for Garmin's status and CTL/ATL/TSB from Garmin's load (`garmin_load_model`) use get_training_status. Returns CTL/ATL/TSB, ACWR, monotony and strain on `to` (`latest`), warning `flags`, ISO weeks per sport (sessions, hours, km, TSS, hrTSS, Garmin load, hours in Z1-2/Z3/Z4-5), the 3-zone intensity split against LT1/LTHR of the last 28 days (Z1/Z2/Z3 minutes and %; answers time below LT1, % in Z1, polarisation) and the thresholds used. include_series adds the daily curve, include_activities TSS/IF/load_source/EF per activity, include_efficiency the monthly EF trend, both with aerobic decoupling (Pa:Hr/Pw:Hr, % EF drop from first to second half) of sessions of 60+ min below LTHR with downloaded laps, include_by_sport CTL/ATL/TSB/ACWR per sport group (`by_sport`, plus run_ctl… columns in the series) next to the total, which stays the default. Example: {"from":"2026-09-01","to":"2026-09-30","include_activities":true}.

Training week or month at a glance: sessions and volume per sport, time in the Garmin HR zones 1-5 (for the 3-zone Z1/Z2/Z3 split against LT1/LTHR, e.g. time below LT1 or polarisation, use get_load), active vs rest days, longest and hardest session, `garmin_load_model` at the end (CTL/ATL/TSB from Garmin's daily training load (EPOC); the own TSS model is get_load), and only avg/min/max of sleep, HRV, resting HR, steps, stress and body battery plus average daily kcal. Day-by-day values and other metrics (calorie totals, intensity minutes, floors, respiration, SpO2) come from query_health, weight from get_body_composition. Weeks run Monday-Sunday. Period "range" gives the same for any from..to up to 366 days, e.g. a training block: {"period":"range","from":"2026-08-04","to":"2026-09-28"}. `complete` is true when the period is over and all its data is in the cache; `training` is left out while its activities are not. Example: {"period":"week","anchor_date":"2026-10-08"}.

Morning GO/MODIFY/REST decision from HRV, resting HR, sleep hours and load; pass `rules` to use your own thresholds. Each signal has its value, reference, rating (ok, yellow, red; unknown when data is missing) and a readable detail; plus rules_used and a recommendation. Garmin's own scores (Training Readiness, Body Battery, stress; sleep score in the sleep value) are shown as info, not counted. REST needs a red pair (hrv with rhr or sleep, load with hrv, rhr or sleep), a single red or 2 yellow give MODIFY; decision_rule "count" instead gives REST at decision_red_min reds. Use for "how am I today" or "can I do a hard session". Example: {"date":"2026-10-12"}.

Sleep for one night ({"date":"2026-10-08"}, the morning date) with stages, score, SpO2, respiration and overnight HRV; or for a range ({"from","to"}) a per-night table with averages and trends.

Thresholds the analytics use on `date` (default today): per param its value, the date it applies since and its source (garmin-auto from the Garmin profile, test, manual, import), by_sport (run, bike, swim: LTHR and LT1 with a note when a fallback, default or approximation), HRmax and the 28-day resting HR. zones has the HR and power zone floors per sport from the Garmin profile (method, HRmax/rest/LTHR or FTP used, fetched date; current, not historical). history adds every recorded row. Example: {"param":"lthr_run","history":true}.

Fitness and fatigue: VO2max (running/cycling) with trend, training readiness, remaining recovery time, Garmin training status (productive, maintaining, ...), Garmin acute/chronic load and load focus (aerobic low/high, anaerobic vs. targets), and `garmin_load_model`: CTL/ATL/TSB from Garmin's daily training load (EPOC); the own TSS model (power, pace, HR) is get_load. `metrics` holds race predictions (5k to marathon), endurance and hill score, fitness age, personal records and heat/altitude acclimation as of the newest training sync on or before `to`. Set include_series for the daily load curve.

Steps of a saved workout in readable form (warm-up, repeats, targets in pace/HR/power).

For "my next race", "what is planned this week" or "which workouts do I have": the saved workout library (`workouts`), scheduled workouts (`upcoming_schedule`) and races or events the user added or subscribed to (`upcoming_events`: date, title, distance, start time, location; `race`/`primary` present only when true, `primary` marks the goal race of an active training plan). The calendar covers `from` to `to` (default: today and the next 60 days); any range works, past or future, and months not in the cache yet are downloaded on the way. Example: {"from":"2027-03-01","to":"2027-05-31"} for races next spring.

For "how did I sleep this week", "calories and intensity minutes this week", "steps yesterday" or any single health metric over days: a table per day or per ISO week plus summary with averages, totals, min/max and 7/28-day trend. Metrics: steps, resting_hr, hrv, sleep, stress, body_battery, respiration, spo2, intensity_minutes, calories, floors. steps also returns the daily distance in km, resting_hr the daily min/max HR, hrv the Garmin HRV status and baseline range, floors the floors climbed, calories the kcal burned (total, active) and eaten (calories_consumed_kcal, absent without food log entries). Ask for several metrics in one call (e.g. calories and intensity_minutes together). Use get_sleep for sleep stages of particular nights. Example: {"metrics":["hrv","resting_hr","sleep"],"from":"2026-07-01","to":"2026-09-30","granularity":"week"}.

Put saved workouts on the Garmin calendar (they then sync to the watch), or take them off it. `unschedule` takes schedule_id values (from list_workouts upcoming_schedule or an earlier schedule_workouts result); the workout stays in the library, only the calendar entry goes. Unschedule only what the user asked to remove. Unscheduling runs first, so moving a workout is one call. Returns a result per item. Examples: {"items":[{"date":"2026-10-10","workout_id":123}]}, {"unschedule":[456]}.

Record a field test result (LTHR, LT1, HRmax, FTP…) effective from a date; ask the user before saving. Stored in the local database only, never sent to Garmin; a row with the same date, param and source stays as it is (added false). A backdated row recomputes earlier activities from its date on (the first garmin-auto row is the Garmin profile as of its first download). Returns the row and the value in effect today. Example: {"date":"2026-10-11","param":"lthr_run","value":171,"note":"30 min TT"}.

Change an activity in Garmin Connect: name, type (Garmin type key such as "trail_running"; valid keys in resource garmin://activity-types), description (notes), rpe (0-10 perceived effort) or feel (0 very weak, 25 weak, 50 normal, 75 strong, 100 very strong). Only call when the user asked for the change. Returns the activity after the edit.