garmin-personal-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GARMIN_BASE_URL | No | The Personal API host. | https://personal.connectapi.garmin.com |
| GARMIN_DATA_DIR | No | The data folder. | ~/workspace/garmin-data |
| GARMIN_API_KEY_FILE | No | The file with the API key. | ~/.config/garmin-mcp/api-key |
| GARMIN_PERSONAL_API_KEY | No | The personal API key. It has priority over the key file. The automatic refresh needs the key file. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| listActivitiesA | List the user's Garmin activities (most recent first) as a compact summary: id, name, type, local start time, distance (km), moving duration, average pace, average/max heart rate, cadence, ascent; when Garmin has them: elapsed time (if longer than moving time), race flag, Garmin training load, aerobic/anaerobic training effect and label, seconds in HR zones 1-5, calories, moderate/vigorous intensity minutes, body battery change, steps, swim SWOLF, pool length, lengths and strokes, power, mountain-bike grit and flow, a ride's km/h, ascent per hour and easy (zones 1-2) and hard (zones 4-5) share of the zone time, running form (stride, ground contact, vertical oscillation and ratio), grade-adjusted pace, best efforts (1k, mile, 5k, 10k, half, marathon) and run/walk segments. Dates are yyyy-MM-dd. Set raw=true for Garmin's full JSON. limit is at most 200; names filters the last 200 activities of the date window. Use it to find activity ids and to compare many activities. For the laps, sets or plan of one activity, give its id to getActivityLaps, getActivitySets or getActivityWorkouts. |
| getActivityA | Garmin's full JSON for one activity: summaryDTO (start time, distance in metres, duration and movingDuration in seconds, averageSpeed in m/s, HR, calories, training effect and load, intensity minutes, Body Battery change, sets and reps of a strength session), splitSummaries (one total per split type, such as the run and walk segments), the activity type and metadataDTO (device maker, lap count, personal record flag). Private ids are left out. Use it for a field that listActivities does not give: listActivities gives the common fields in km and min/km, for many activities in one call. It has no laps, sets or samples: use getActivityLaps, getActivitySets or downloadActivityFit for them. |
| getActivityWorkoutsA | The planned workout that an activity followed, as created in Garmin Connect: its steps in order, each with its intensity (warmup/active/rest/recovery/cooldown), its duration (time in seconds, reps, or open), its target (cadence, heart rate, pace, or open, with low and high values), the exercise for strength steps, and the coach's notes. A step with durationType REPEAT_UNTIL_STEPS_CMPLT repeats the steps from stepIndex durationValue up to it, targetValue times in all. Use it for the whole plan and its notes. For plan against done (hit or miss), read the plan field of getActivitySets (strength) or getActivityLaps (runs) instead; a ride or a swim has no plan field. An empty list means the activity followed no planned workout. Null fields are left out. |
| downloadActivityFitA | Download the ORIGINAL .FIT file of an activity and save it on the user's computer. Returns the absolute path of the saved .fit file (second-by-second HR, cadence, speed, laps). The file is saved once in the fit folder of the data dir; a later call does not download it again. Use it only when the user wants the file itself: getActivityLaps and getActivitySets already read it. |
| getActivityLapsA | Laps of an activity as recorded by the watch (manual laps, auto-lap every km, or workout steps), read from the original .FIT file. One row per lap: distance (km), timer time, pace (min/km, foot sports) or speed (km/h), average/max HR, cadence (spm for running), ascent/descent, average power, running form (gctMs, vertRatioPct, vertOscCm, strideCm), intensity (active, interval, rest, recovery, warmup, cooldown; the auto laps of a free run can be interval), lap trigger, and the step of the planned workout (step: the reps of one drill share it). A swim lap also has metres, swimPace (per 100 m), stroke, lengths, swolf and strokes. Use it for intervals and per-km splits; getActivity does not have them. For a run: split (pace of the first and second half, kind, hrDriftPct) and, for a structured workout, work (reps, pace, avgHR, and the fade of each step with more than one rep, pct). For a swim: sets, the laps in a row of one distance, stroke and intensity (reps, firstPace, lastPace, pct: above 0 is slower, firstSwolf, lastSwolf). null is n/a. For a run, plan is the planned workout that the watch ran (null without one): its name and, per lap with a step in lap order, the step's target (type, low, high, unit; or zone), done (the lap in that unit), verdict (hit inside the target, ends included, or miss) and off (how far outside, in the unit: s/km for pace, above 0 is slower). An open or zone target, a target in %max or %ftp, a target outside a plausible range, a lap under 15 m or 8 s or a lap without the value has verdict null. |
| getActivitySetsA | Strength training sets of an activity, read from the original .FIT file. One entry per exercise, in the order first done, with its movement category, its primary and secondary muscles (from Garmin's exercise catalogue) and its active sets: reps, weight (kg, absent when none was recorded), set time in seconds and the rest after the set (restSec). Each exercise with weight also has top (the heaviest set of 1 to 12 reps, then the most reps; without one, the heaviest set) and e1rmKg (the best estimated 1RM, Epley, of its sets of 1 to 12 reps; null when it has none). Exercise names are stable across sessions, so they can be used for per-exercise trends. Edits made later in Garmin Connect (renamed exercises, corrected reps or weights) are not in the .FIT file. Use it for strength sessions; for runs, rides and swims use getActivityLaps. plan is the planned workout that the watch ran (null without one): its name and, per planned exercise and rep plan (a pyramid gives a row per rep plan) in plan order, plannedSets, plannedReps (low to high; high null is at least low), doneSets, reps, and verdict (hit or miss, why: sets or reps; extra and over count the done sets above the plan and above the high end); a warm-up or cool-down row (part) and a notInPlan row have verdict null. In a rest-pause group (a repeat of one exercise with a rest of 20 s or less inside it and a longer rest after it), only the first set of each pass is judged on reps. Such a row has restPause true. Each planned row also has plannedRestSec: the planned rests right after its sets, in seconds and plan order (null: an open rest, ended with the lap button; empty: no rest right after it, such as the first exercise of a superset). |
| getHrvRangeA | Overnight HRV for a date range, yyyy-MM-dd: hrvSummaries, one row per night with HRV data (a night without data has no row), with calendarDate, lastNightAvg (ms, the average of the night), lastNight5MinHigh, weeklyAvg (the 7-night average), status (BALANCED, UNBALANCED or LOW) and baseline (balancedLow to balancedUpper: the normal range). Ask at most 28 days in one call: Garmin may refuse a longer range. Use it for the HRV trend; for the sleep of a night use getSleep, and for resting HR use getDailyHeartRate or getDailySummary. |
| getDailyHeartRateA | Heart rate of one day, yyyy-MM-dd: restingHeartRate, minHeartRate and maxHeartRate (bpm), lastSevenDaysAvgRestingHeartRate, and heartRateValues, the samples of the day as [timestamp, bpm] pairs (several hundred, so the answer is about 13 KB). Use it for the HR curve of a day. For resting HR over several days use getDailySummary with fromDate and toDate; for the zone limits use getHeartRateZones. |
| getSleepA | Sleep for one night (date: the morning you woke up), or for up to 14 nights (fromDate and toDate), yyyy-MM-dd, as one compact row per night: bedtime and wake (local HH:mm), hours of sleep, deep, light, REM and awake, the sleep score and its quality, the sleep need (hours), average heart rate, average and lowest SpO2, average respiration, awake count, average sleep stress and Garmin's feedback. Missing values are left out, and a night without sleep data has only its date. Set raw=true for Garmin's JSON. |
| getWeightA | Weight for a date range, yyyy-MM-dd: the latest weight of each day (with body fat, muscle and bone mass, BMI and body water when a scale records them), the average of the range, and the last weight before and the first after the range. Set includeAll=true for every entry of each day. Weight, muscle mass and bone mass are in grams. The range has no day cap: ask a trend of months in one call. |
| getBodyBatteryA | Body Battery for up to 14 days, yyyy-MM-dd: for each day how much it charged and drained, its readings through the day as [timestamp, level] pairs, and the events that changed it (sleep, activities, stress, naps) with their start, duration and impact, and Garmin's feedback. Use it to see why Body Battery went up or down. For one number per day with steps and stress use getDailySummary; for the change of one activity, listActivities. |
| getHeartRateZonesA | The heart rate zones set in Garmin Connect: a list with one entry per sport that has its own zones (sport DEFAULT for the others), each with trainingMethod (how Garmin sets the zones), zone1Floor to zone5Floor (the lowest bpm of each zone; a zone ends where the next one starts, zone 5 at maxHeartRateUsed), maxHeartRateUsed, restingHeartRateUsed and lactateThresholdHeartRateUsed. It takes no parameters. It gives the limits only: the time in each zone of an activity is hrZonesSec in listActivities. |
| getFitnessAgeA | Garmin fitness age for a date, yyyy-MM-dd: fitnessAge, chronologicalAge, achievableFitnessAge and previousFitnessAge, and components: bodyFat, vigorousDaysAvg and vigorousMinutesAvg (per week) and rhr (resting HR), each with its value and, when Garmin suggests one, targetValue and potentialAge (the fitness age at the target). stale is Garmin's flag for an old value. Use it for fitness age; for the body fat trend use getWeight. |
| getDailySummaryA | Daily user summary (steps, calories, stress, body battery, resting HR) for one date, or for up to 14 days (fromDate and toDate; the range answer has Garmin's v2 field names), yyyy-MM-dd. Use it for the totals of each day; for sleep use getSleep, for the Body Battery events getBodyBattery, and for the HR samples getDailyHeartRate. |
| garminGetA | Generic read-only GET on the Garmin Connect Personal API, for endpoints not covered by the other tools or when a query parameter name has to be adjusted. 'path' is relative and starts with '/', e.g. /fitnessage-service/fitnessage/v2/2026-10-25 . 'query' is an optional URL query string without '?', e.g. date=2026-10-25&foo=bar . |
| getDashboardDataA | All the data of the training dashboard in one call: HR zones, fitness age, the activities of the
last |
| writeDashboardA | Writes the training dashboard page (default /garmin-dashboard.html) with the data of the
last |
| editDashboardA | Changes the layout, the custom widgets or the languages of the dashboard page (a page from the
template; call writeDashboard first). Without arguments it only reads: the reply has the layout, the
custom widgets, the missing texts of each language, the catalogue of built-in widgets and |
| showDashboardA | Shows the training dashboard in the chat, in assistants that show MCP Apps: the page of |
| scheduleDashboardRefreshA | Turns on, changes or stops the automatic refresh of a dashboard page. Use it only when the user
asks for it or says yes to the question of a dashboard prompt. A job in the scheduler of the
computer (launchd, cron or Task Scheduler) replaces the data of the page at the given times, also
with no assistant open. The refresh removes the coach notes, because old notes do not agree
with new data. The computer must be on at that time. The page must exist (writeDashboard first).
|
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| training-dashboard | Build a personal training + recovery dashboard (volume, load, HRV, sleep) from Garmin data |
| training-dashboard-update | Update the training dashboard with the new Garmin data; it keeps the layout, widgets and languages |
| dashboard-widget | Make a new widget for the training dashboard from your idea |
| dashboard-setup | Set up a dashboard: title, sports, the data it shows (e.g. for a coach), languages, themes, file |
| dashboard-language | Add a language to the training dashboard (the assistant translates its texts) |
| run-review | Review a run as a coach: planned workout against the laps, rep fade, HR drift, recovery |
| strength-review | Review a strength session as a coach: planned sets against done, top sets, rest, recovery |
| race-readiness | Check if you are ready for a race: training block, taper, predicted time, recovery, race plan |
| swim-review | Review a swim as a coach: planned workout against the laps, set fade, SWOLF and strokes, recovery |
| ride-review | Review a ride as a coach: speed, climbing, power, grit and flow, the same route before, recovery |
| swim-readiness | Check if you are ready for a swim event: training block, longest swim, pace, CSS, recovery |
| train-today | Tell if you should train hard today: the dashboard's readiness verdict, its inputs, fitness and form |
| week-review | Review the last whole training week against the weeks before: sessions, hours, km, load and form |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Training dashboard | The dashboard page that showDashboard fills |
TDQS
Scored across 20 tools
Most tools target clearly distinct Garmin resources or actions: weight, sleep, HRV, activities, laps, sets, workouts, and FIT download are well separated. The main ambiguity is the dashboard cluster: getDashboardData, writeDashboard, showDashboard, editDashboard, and scheduleDashboardRefresh overlap in purpose, though their descriptions clarify the boundaries. garminGet is intentionally a fallback and could be confused with covered endpoints, but its generic nature is explicit.
All tool names use camelCase, which is consistent, and most follow a verb_noun pattern such as getSleep, listActivities, downloadActivityFit, and scheduleDashboardRefresh. There are minor deviations: garminGet is an odd prefix/verb construction, and the dashboard tools use write/edit/show rather than a uniform get/manage pattern. Overall the naming is predictable and readable.
Twenty tools is slightly heavy but appropriate for a Garmin personal data server that spans health metrics, activities, .FIT-derived detail, dashboard generation, and dashboard scheduling. Each tool generally earns its place by covering a specific data source or workflow. It is near the upper end of comfortable scope but not excessive for the domain.
The surface is broad for read-oriented Garmin analytics: daily summaries, sleep, HRV, heart rate, body battery, weight, fitness age, activities, activity laps/sets/workouts, and dashboard management. Minor gaps exist for some standalone metrics and profile/settings actions, but garminGet provides a generic fallback. Core lifecycle coverage for the dashboard is present, including write, edit, show, and scheduled refresh.