GarminMCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GARMIN_EMAIL | No | Optional Garmin Connect email for headless fallback login. | |
| GARMIN_UNITS | No | Unit system for distances, paces, elevations, and weights: metric or imperial. | metric |
| GARMIN_MCP_PORT | No | HTTP port when running in streamable-http or sse transport mode. Defaults to 8000 or $PORT. | 8000 |
| GARMIN_PASSWORD | No | Optional Garmin Connect password for headless fallback login. | |
| GARMIN_CACHE_DIR | No | Directory for the SQLite TTL cache (cache.db). | ~/.cache/garmin-coach-mcp |
| GARMIN_CACHE_TTL | No | Default cache TTL in seconds for daily telemetry. | 900 |
| GARMIN_TOKEN_DIR | No | Directory storing oauth1_token.json and oauth2_token.json with 0700 permissions. | ~/.garminconnect |
| GARMIN_TOKEN_BASE64 | No | Base64-encoded token bundle produced by garmin-coach-mcp export-tokens for stateless Cloud Run / container deployments. Automatically hydrates GARMIN_TOKEN_DIR with 0600 file permissions on startup. | |
| GARMIN_MCP_TRANSPORT | No | MCP transport mode: stdio, streamable-http, or sse. | stdio |
| GARMIN_MCP_AUTH_TOKEN | No | Bearer token secret required for remote streamable-http / sse requests when set. Requests must include Authorization: Bearer <token>. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Elite Personal Health, Running, and Fitness Coach MCP Server powered by Garmin Connect telemetry.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_coach_daily_briefingA | Fetch a complete morning coaching briefing for a single date (defaults to today). Coaching Purpose:
High-level morning readiness aggregator designed to be the first tool called
in a daily check-in. Synthesizes Training Readiness score & contributors,
Body Battery (current, charged, drained), overnight Sleep quality & stages,
Heart Rate Variability (HRV) status vs. personal baseline, Resting Heart Rate
(RHR vs. 7-day baseline), daily Stress, and yesterday's completed workouts into
an actionable training intensity prescription ( Args:
target_date: Target ISO calendar date ( Returns: Formatted coaching briefing containing readiness score, autonomic recovery metrics, sleep architecture, yesterday's training load, and today's recommended workout intensity. |
| get_sleep_and_recoveryA | Analyze overnight sleep architecture, HRV vs. baseline, SpO2, respiration, and Body Battery recharge. Coaching Purpose: Evaluates multi-day or single-night sleep quality and autonomic nervous system recovery. Useful for diagnosing cumulative sleep debt, suppressed nocturnal HRV, elevated sleeping heart rate/respiration (early illness or overreaching markers), and poor Body Battery recharge. Args:
start_date: Start ISO date ( Returns: Formatted sleep & recovery analysis including deep/light/REM/awake sleep stages, sleep score, SpO2, respiration rate, overnight HRV + baseline, and Body Battery recharge. |
| get_training_status_and_loadA | Retrieve VO2 Max, Acute/Chronic Load (ACWR), Training Status, Recovery Time, Fitness Age, and Endurance/Hill scores. Coaching Purpose: Quantifies macro- and meso-cycle training load progression and aerobic fitness adaptations. Assesses whether the athlete is Productive, Peaking, Maintaining, Strained, or Overreaching, inspects Acute-to-Chronic Workload Ratio (ACWR) for injury-risk management, and checks low/high aerobic vs. anaerobic load balance. Args:
target_date: Target ISO date ( Returns: Formatted report of VO2 Max (running/cycling), Acute Load, Chronic Load, ACWR load ratio, Training Status, Recovery Time remaining, Fitness Age, Endurance Score, and Hill Score. |
| list_recent_activitiesA | List recent workouts with distance, duration, HR, pace/power, elevation, calories, and Training Effect. Coaching Purpose: Provides a scannable training log across running, cycling, swimming, strength, and cardio sessions. Supports filtering by workout type and date range to inspect training consistency, session load distribution, and recent activity IDs for deep-dives. Args:
limit: Maximum number of activities to return (default Returns: Formatted activity log containing activity IDs, distances, durations, average/max HR, pace/power, elevation gain/loss, calories, and aerobic/anaerobic Training Effect. |
| get_activity_detailsA | Perform a granular post-workout debrief for a specific Garmin activity ID. Coaching Purpose: Deep-dives into a single completed workout to evaluate interval execution, lap-by-lap pacing stability, time spent in Heart Rate and Power/Pace zones, elevation gain/loss, running/cycling cadence, first-half vs. second-half cardiac drift percentage, and environmental weather stress. Args:
activity_id: Numeric or string Garmin Connect activity ID (obtainable via Returns: Formatted deep-dive workout analysis including lap/split breakdowns, HR zone distribution, power/pace zone distribution, cardiac drift %, pacing assessment, and weather conditions. |
| get_health_trendsA | Compute longitudinal rolling averages, first-half vs. second-half deltas, and training volume over N days. Coaching Purpose: Detects multi-week physiological trends and early overtraining signals across Resting Heart Rate (RHR), overnight HRV, sleep duration, daily steps, daily stress, and total training volume (hours, distance, activity breakdown) over a configurable window (e.g., 7, 14, 28, 30, or 90 days). Args:
days: Number of days to aggregate (default Returns: Formatted longitudinal trend report with biomarker averages, min/max, 1st-half vs. 2nd-half deltas, trend directions, training volume totals, and diagnostic coach flags. |
| get_body_composition_and_biometricsA | Fetch weight trends, body fat %, muscle mass, hydration, and physiological thresholds (LTHR, Max HR, FTP). Coaching Purpose: Tracks body composition shifts (weight, body fat percentage, skeletal muscle mass, body water, BMI), daily hydration intake, and physiological threshold anchors (Lactate Threshold Heart Rate & Pace, Max HR, Resting HR, Cycling FTP, VO2 Max) used to calibrate training zones and race power/pacing targets. Args:
start_date: Start ISO date ( Returns: Formatted body composition and biometrics report with weight delta, weigh-in history, hydration averages, and Lactate Threshold / Max HR / FTP configurations. |
| create_structured_workout_jsonA | Validate, build, and optionally upload a structured Garmin Connect workout. Coaching Purpose:
Translates a coach's workout prescription (warmups, intervals, recovery jogs,
nested repeat blocks, cooldowns with time/distance/lap-button durations and
HR/pace/power/cadence targets) into a schema-validated Garmin Connect
Args:
workout_name: Descriptive title for the workout (e.g., Returns:
Formatted workout summary and validated Garmin Connect workout JSON payload
(including |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| morning-readiness-check | Calls get_coach_daily_briefing to evaluate Training Readiness, Body Battery, overnight HRV, and sleep quality, outputting a structured readiness score, recovery bottlenecks, and today's workout adjustment. |
| post-workout-debrief | Analyzes a specific activity_id (or latest activity via list_recent_activities) using get_activity_details and get_training_status_and_load to evaluate pacing evenness, cardiac drift, and HR/power/pace zone compliance. |
| weekly-training-plan | Audits the last 28 days of training load and biomarker trends (get_health_trends, list_recent_activities, get_training_status_and_load) to build a periodized 7-day training plan tailored to the athlete's goal, with optional structured workout JSON export. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| athlete_profile | Static and semi-static Garmin athlete profile including configured Heart Rate Zones, Pace Zones, Power Zones, Max HR, Lactate Threshold, and Personal Records (PRs) in Markdown + JSON. |
| coach_context_today | Dynamic coaching context resource returning today's complete Training Readiness, Body Battery, Sleep, HRV, RHR, and workout intensity recommendation in clean Markdown. |
TDQS
Scored across 8 tools
Each tool targets a distinct analysis slice (daily readiness, sleep/recovery, training load, activity list, activity deep-dive, longitudinal trends, body composition, workout creation), so misselection risk is low. The only real overlap is get_coach_daily_briefing, which re-synthesizes HRV, sleep, Body Battery, and yesterday's workouts that dedicated tools also return, but it is explicitly framed as the entry-point aggregator, which mitigates confusion.
All eight tools follow a clean verb_noun snake_case convention with consistent prefixes (get_*, list_*, create_*) and domain-descriptive nouns. Requests are parameterized uniformly with target_date/start_date/end_date and response_format across the read tools.
Eight tools is well-scoped for a Garmin coaching/analytics server: one aggregator, five focused health/training readers, one activity deep-dive, and one workout builder. Each tool occupies a distinct analytical role without redundant entries.
The read surface is comprehensive for a coaching domain (readiness, sleep, load, activity list+details, trends, biometrics), and workout creation is covered. The notable gap is workout lifecycle management: there is no way to list scheduled/uploaded workouts, update or delete one after create_structured_workout_json, nor any calendar/planned-workout visibility, which could force workarounds.