Skip to main content
Glama

garmin-mcp-modal

This repo runs garmin_mcp, an MCP server for Garmin Connect, on Modal. Your MCP clients (claude.ai, Claude Code, or any other client that connects to a URL) can then read your Garmin data without a server on your own computer.

By default the server offers only tools that read data. Modal rejects every request that does not carry your proxy token, which is a key and secret that you create in Modal. The server runs only while it handles requests, and it stops after 1 minute without one.

What you need

  • uv.

  • A Modal account. The free Starter plan is enough.

  • The Modal CLI, logged in: run uv tool install modal, then modal setup.

  • A Garmin Connect account.

The commands below are for macOS and Linux shells. On Windows, run them in WSL.

Related MCP server: Garmin MCP

Set up

  1. Clone this repo and open a terminal in it.

  2. Log in to Garmin to create a token for the server. The command asks for your email, password and MFA code:

    uv run garmin-mcp-auth --token-path ~/.garminconnect-modal --force-reauth

    The token goes into its own folder, so that the server does not share a login with a copy of garmin_mcp that runs on your computer. --force-reauth makes it log in again even when an older token is already there.

  3. Deploy the server:

    modal deploy modal_app.py

    The output shows the server URL, for example https://<workspace>--garmin-mcp-serve.us-east.modal.run.

  4. Upload the Garmin token:

    modal volume put garmin-tokens ~/.garminconnect-modal/garmin_tokens.json /garmin_tokens.json
  5. Create a proxy token. Modal shows the secret only once, so save the key and the secret in your password manager:

    modal workspace proxy-tokens create
  6. Test the server with your proxy token's ID and secret:

    MODAL_KEY=wk-... MODAL_SECRET=ws-... uv run scripts/smoke_test.py

    Each result line starts with [PASS] when the server works. If a line fails, or a client can't connect later, the server logs show why: modal app logs garmin-mcp.

Connect a client

Give your client the server URL with /mcp at the end, and this request header, with your proxy token's ID and secret joined by a dot:

Authorization: Bearer <token-id>.<token-secret>

For example, Bearer wk-abc123.ws-def456.

Modal also accepts the token as two headers, Modal-Key and Modal-Secret. Use these if your client already uses the Authorization header for something else.

In claude.ai, add the server as a custom connector. Under Authentication, choose No sign-in, and put the Authorization header under Request headers. The connector then works in claude.ai on the web, desktop and mobile, and in Claude Code.

Other clients work if they support the Streamable HTTP transport and let you set request headers.

Choose the tools

To change which tools the server offers, set these variables in the same command as modal deploy. The deploy reads them from your shell, including any that you set earlier for a local garmin_mcp. A deploy without them goes back to the default of all read-only tools.

Variable

Effect

GARMIN_TOOL_PROFILE

Offers only the tools for one area: health, activities, training, workouts, nutrition or minimal. To combine areas, separate them with commas.

GARMIN_ENABLED_TOOLS

A comma-separated list of tool names. Without a profile, the server offers only these tools. With a profile, they are added to it. Write tools are left out unless GARMIN_MCP_ALLOW_WRITES is true.

GARMIN_DISABLED_TOOLS

A comma-separated list of tool names to remove.

GARMIN_MCP_ALLOW_WRITES

true also offers the tools that create, change or delete data in Garmin Connect.

For example:

GARMIN_TOOL_PROFILE=health modal deploy modal_app.py

Before you set GARMIN_MCP_ALLOW_WRITES=true, set your client to ask for approval before it uses a write tool. With write tools on, anyone who has your proxy token can change or delete your Garmin data.

When Garmin tools return authentication errors

The server renews its Garmin access token every day without your help. The login behind it lasts for months, but it can end, for example when you change your Garmin password. To log in again:

  1. Stop the server, so that it does not write its old token over the new one:

    modal app stop garmin-mcp
  2. Log in again, as in step 2 of the setup.

  3. Upload the new token. --force replaces the old file:

    modal volume put --force garmin-tokens ~/.garminconnect-modal/garmin_tokens.json /garmin_tokens.json
  4. Deploy again, with the same tool variables as before.

Update garmin_mcp

  1. In pyproject.toml, change rev to the new commit of garmin_mcp.

  2. Run uv lock.

  3. Deploy again and run the smoke test.

License

MIT. See LICENSE. garmin_mcp is also MIT-licensed.

Available Tools

157 tools
add_body_compositionA

Add body composition data

    Args:
        date: Date in YYYY-MM-DD format
        weight: Weight in kg
        percent_fat: Body fat percentage
        percent_hydration: Hydration percentage
        visceral_fat_mass: Visceral fat mass in kg (not grams)
        bone_mass: Bone mass in kg (not grams)
        muscle_mass: Muscle mass in kg (not grams)
        basal_met: Basal metabolic rate in kcal/day
        active_met: Active metabolic rate in kcal/day
        physique_rating: Physique rating
        metabolic_age: Metabolic age
        visceral_fat_rating: Visceral fat rating
        bmi: Body Mass Index
    

Inputs: date (required), weight (required), bmi, basal_met, +9 more.

add_gear_to_activityB

Associate gear with an activity

    Links a specific piece of gear (like shoes, bike, etc.) to an activity.

    Args:
        activity_id: ID of the activity
        gear_uuid: UUID of the gear to add (get from get_gear)
    

Inputs: gear_uuid (required), activity_id (required).

add_hydration_dataB

Add hydration data

    Args:
        value_in_ml: Amount of liquid in milliliters
        cdate: Date in YYYY-MM-DD format
        timestamp: Timestamp in YYYY-MM-DDThh:mm:ss.sss format
    

Inputs: cdate (required), timestamp (required), value_in_ml (required).

add_weigh_inB

Add a new weight measurement

    Args:
        weight: Weight value
        unit_key: Unit of weight ('kg' or 'lbs'; 'lb' is accepted as an alias)
    

Inputs: weight (required), unit_key.

add_weigh_in_with_timestampsA

Add a new weight measurement with specific timestamps

    If both timestamps are omitted, the current time is used. If only
    date_timestamp is given, the GMT timestamp is derived from it.

    Args:
        weight: Weight value
        unit_key: Unit of weight ('kg' or 'lbs'; 'lb' is accepted as an alias)
        date_timestamp: Local timestamp in format YYYY-MM-DDThh:mm:ss
            (required if gmt_timestamp is given -- it sets the day the
            weigh-in is recorded on)
        gmt_timestamp: GMT timestamp in format YYYY-MM-DDThh:mm:ss
    

Inputs: weight (required), unit_key, gmt_timestamp, date_timestamp.

count_activitiesA
Read-only

Get total count of activities in the user's Garmin account

Returns the total number of activities recorded.

Inputs: no named parameters.

create_custom_foodA

Create a custom food in the user's Garmin nutrition library

    Creates a new food item with nutritional information per serving.
    On success the response includes foodId and servingId needed for
    log_custom_food. If the API returns no data (204), use
    get_custom_foods(search=food_name) to retrieve those IDs.

    All nutrient amounts are ABSOLUTE values per serving, not %DV.
    Nutrition labels often print %DV for calcium/iron/vitamin D —
    convert to absolute units before passing.

    Args:
        food_name: Name of the custom food (e.g. "Homemade Chocolate Cookies")
        calories: Calories per serving
        serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G"
        number_of_units: Serving size in the specified unit. Default 100
        brand_name: Brand or vendor name (e.g. "Three Bridges")
        carbs: Carbohydrates in grams per serving
        protein: Protein in grams per serving
        fat: Total fat in grams per serving
        fiber: Fiber in grams per serving
        sugar: Sugar in grams per serving
        saturated_fat: Saturated fat in grams per serving
        sodium: Sodium in mg per serving
        cholesterol: Cholesterol in mg per serving
        potassium: Potassium in mg per serving
        trans_fat: Trans fat in grams per serving
        calcium: Calcium in mg per serving (NOT %DV)
        iron: Iron in mg per serving (NOT %DV)
        vitamin_d: Vitamin D in mcg per serving (NOT %DV)
    

Inputs: calories (required), food_name (required), fat, iron, +14 more.

create_manual_activityA

Log a manual activity in Garmin Connect — useful for activities done without a watch.

    The type_key must match a Garmin activity type. Use get_activity_types to see
    the full list. Common values: yoga, strength_training, meditation, indoor_cycling,
    pilates, bouldering, fitness_equipment.

    Args:
        type_key: Activity type key (e.g. "yoga", "strength_training")
        date: Date of the activity in YYYY-MM-DD format
        duration_minutes: Duration of the activity in minutes
        start_time: Start time as HH:MM (24-hour, default 09:00)
        activity_name: Optional title; defaults to the type_key if not provided
        distance_km: Distance in kilometres (default 0.0 for non-distance activities)
        time_zone: IANA time zone for the activity (default UTC)

    If a write fails with write_committed="unknown", check whether the
    activity exists before retrying to avoid creating a duplicate.
    

Inputs: date (required), type_key (required), duration_minutes (required), time_zone, +3 more.

create_run_interval_workoutA

Create a repeat-based interval run workout and upload it to Garmin Connect.

    Builds warmup -> repeats x [work interval + jog recovery] -> cooldown. Use this
    instead of create_run_workout whenever the session has more than one work
    interval (threshold reps, VO2 intervals, cruise intervals, strides).

    Work intervals target a named heart-rate zone by default, but named zones are
    usually far too wide for interval work: a threshold session at 172-180 bpm sits
    inside a Z3 that may span 158-184. Pass hr_min and hr_max together to target the
    exact bpm range, so the watch alerts as soon as the effort drifts off target.

    Recovery steps carry no target unless recovery_hr_min/max are given -- a capped
    recovery alerts constantly right after a hard rep, since heart rate lags effort.
    Recovery HR bounds require recovery_seconds > 0.

    Example -- 3 x 6 min at HR 172-180 with 3 min jogs, 12m warmup, 8m cooldown:
        repeats=3, rep_seconds=360, recovery_seconds=180,
        hr_min=172, hr_max=180, warmup_min=12, cooldown_min=8

    Args:
        name: Workout name (e.g. "Threshold 3x6min")
        repeats: Number of work intervals
        rep_seconds: Duration of each work interval in seconds
        recovery_seconds: Jog recovery between work intervals in seconds (0 to omit)
        warmup_min: Warmup duration in minutes
        cooldown_min: Cooldown duration in minutes
        hr_zone: Target zone for the work intervals (Z1-Z5, default Z4). Ignored if hr_min/hr_max are given.
        hr_min: Custom target HR range for the work intervals, minimum bpm (with hr_max)
        hr_max: Custom target HR range for the work intervals, maximum bpm (with hr_min)
        recovery_hr_min: Optional HR range for recovery jogs, minimum bpm (with recovery_hr_max)
        recovery_hr_max: Optional HR range for recovery jogs, maximum bpm (with recovery_hr_min)
    

Inputs: name (required), repeats (required), warmup_min (required), rep_seconds (required), +7 more.

create_run_workoutA

Create a continuous run workout and upload it to Garmin Connect.

    Builds a single uninterrupted run interval with warmup and cooldown walks.

    Targets a named Garmin heart-rate zone by default. Named zones (Z1-Z5)
    don't line up with every real training target -- e.g. a 136-148 bpm
    Zone 2 goal straddles Garmin's Z2 (118-137) and Z3 (138-157). Pass
    hr_min and hr_max together to target that exact bpm range instead;
    the watch will then show "in range" only for the range you actually
    want, not a whole zone that over- or under-shoots it.

    Args:
        name: Workout name (e.g. "Step 8 - 30min continuous")
            Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
        run_seconds: Duration of the run in seconds
        warmup_min: Warmup walk duration in minutes
        cooldown_min: Cooldown walk duration in minutes
        hr_zone: Target heart-rate zone (Z1-Z5, default Z3). Ignored if hr_min/hr_max are given.
        hr_min: Optional custom target heart rate range, minimum bpm (must be given with hr_max)
        hr_max: Optional custom target heart rate range, maximum bpm (must be given with hr_min)
    

Inputs: name (required), warmup_min (required), run_seconds (required), cooldown_min (required), +3 more.

create_strength_workoutA

Create a strength workout and upload it to Garmin Connect.

    Each exercise becomes a reps-based step; when sets > 1 the exercise is
    emitted as a repeat group of that many iterations (work + rest per set),
    so Garmin shows the real set count. The name is kept in the step
    description; it is also sent as exerciseName, which Garmin only retains when
    it matches one of its own exercise keys (e.g. "FARMERS_CARRY").

    Args:
        name: Workout name
            Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
        exercises: List of dicts with keys: name, sets, reps, rest_seconds and an
            optional category. Category is omitted from the payload when not
            given; Garmin accepts that. When given it must be one of Garmin's
            exercise categories (e.g. SQUAT, DEADLIFT, PUSH_UP, CARRY, SLED) —
            anything else, including "UNASSIGNED" and "OTHER", is rejected with
            400 Invalid category. Full list:
            https://connect.garmin.com/web-data/exercises/Exercises.json
    

Inputs: name (required), exercises (required).

create_walk_run_workoutA

Create a walk/run interval workout and upload it to Garmin Connect.

    Builds the internal Garmin JSON automatically and returns the new workout ID.

    Args:
        name: Workout name (e.g. "W3 Mié 2:2")
            Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
        run_seconds: Duration of each run interval in seconds
        walk_seconds: Duration of each walk/recovery interval in seconds
        repeats: Number of run/walk repetitions
        warmup_min: Warmup duration in minutes
        cooldown_min: Cooldown duration in minutes
        hr_zone: Target heart-rate zone (Z1-Z5, default Z3)
    

Inputs: name (required), repeats (required), warmup_min (required), run_seconds (required), +3 more.

create_z2_walk_workoutA

Create a steady Z2 walking workout and upload it to Garmin Connect.

    Args:
        name: Workout name
            Max 256 characters: Garmin SILENTLY TRUNCATES longer names.
        duration_min: Main walking block duration in minutes
        hr_min: Minimum heart rate in bpm (used for description; target is Z2)
        hr_max: Maximum heart rate in bpm (used for description; target is Z2)
    

Inputs: name (required), hr_max (required), hr_min (required), duration_min (required).

delete_activityA
Destructive

Permanently delete an activity from Garmin Connect.

    This cannot be undone. Call once with confirm=false (the default) to
    preview the activity, then call again with confirm=true to delete it.
    confirm=true is the scripting equivalent of a force flag.

    Args:
        activity_id: ID of the activity to delete
        confirm: Must be true to actually delete. Default false returns a preview.
    

Inputs: activity_id (required), confirm.

delete_courseA
Destructive

Delete a course from Garmin Connect.

    This cannot be undone. Call once with confirm=false (the default) to
    preview the course, then call again with confirm=true to delete it.

    Args:
        course_id: ID of the course to delete (get IDs from get_courses).
        confirm: Must be true to actually delete. Default false returns a preview.
    

Inputs: course_id (required), confirm.

delete_custom_foodA
Destructive

Delete a custom food from the user's Garmin nutrition library

    Permanently removes a custom food entry — this cannot be undone and
    the deleted food's name/brand/nutrition data cannot be recovered from
    the API afterward. The default call previews the food without deleting
    it. Review that preview, then call again with confirm=true.

    Deleting a food does NOT require it to be unreferenced: existing food
    log entries that already reference this food are NOT blocked or
    removed — they remain in the log (their nutrition still counts toward
    daily totals) but are marked inactive (foodInactive: true) and can no
    longer be edited/re-logged from the library.

    Use get_custom_foods to find the foodId, and match on the exact
    foodId (not just a name search) — Garmin's search can return loosely
    related results for a given search term, not just exact matches.

    Args:
        food_id: ID of the custom food to delete — a 32-char hex string
            (from get_custom_foods or create_custom_food)
        confirm: Set true to delete after reviewing the default preview
    

Inputs: food_id (required), confirm.

delete_food_logA
Destructive

Delete a food log entry

    Permanently removes a logged food item from the nutrition log.
    Works for both QUICK_ADD and REGULAR_LOG entry types.
    Use get_nutrition_daily_food_log to find the logId and date. The default
    call previews the matching entry; call again with confirm=true to delete.

    Args:
        log_id: Log entry ID to delete — a 32-char hex UUID
            (from get_nutrition_daily_food_log)
        meal_date: Date of the log entry in YYYY-MM-DD format
        confirm: Set true to delete after reviewing the default preview
    

Inputs: log_id (required), meal_date (required), confirm.

delete_weigh_insA
Destructive

Delete weight measurements for a specific date

    Permanently removes the selected day's weigh-ins. This cannot be undone.
    Call once with confirm=false (the default) to preview the measurements,
    then call again with confirm=true to delete them.

    Args:
        date: Date in YYYY-MM-DD format
        delete_all: Whether to delete all measurements for the day
        confirm: Set true after reviewing the preview to perform the deletion
    

Inputs: date (required), confirm, delete_all.

delete_workoutA
Destructive

Delete a workout from Garmin Connect

    Permanently removes a workout from your Garmin Connect workout library.
    This cannot be undone. Call once with confirm=false (the default) to
    preview the workout, then call again with confirm=true to delete it.

    Args:
        workout_id: ID of the workout to delete (get IDs from get_workouts)
        confirm: Must be true to actually delete. Default false returns a preview.
    

Inputs: workout_id (required), confirm.

delete_workoutsA
Destructive

Delete multiple workouts from Garmin Connect in a single call

    Permanently removes multiple workouts from your Garmin Connect workout library.
    This cannot be undone. Call once with confirm=false (the default) to
    preview the workouts, then call again with confirm=true to delete them.

    Args:
        workout_ids: List of workout IDs to delete (get IDs from get_workouts)
        confirm: Must be true to actually delete. Default false returns a preview.
    

Inputs: workout_ids (required), confirm.

download_activity_fileA
Destructive

Download an activity and save it to disk as a file.

    Saves the activity in the requested format. Defaults to the original .fit
    file; Garmin also supports gpx, tcx, and csv.

    Directory resolution (first match wins):
      1. output_dir argument (one-off; not persisted)
      2. GARMIN_FIT_DOWNLOAD_DIR environment variable
      3. persisted config (set via set_fit_download_dir)
    If none is configured, returns status "needs_setup" with a suggested
    default (the server's current working directory). In that case, ask the
    user where to save, call set_fit_download_dir(path), then call this tool
    again.

    Files are named "{activity_id}.{ext}" and overwrite any existing file.

    Args:
        activity_id: Garmin activity ID
        format: One of fit, gpx, tcx, csv (default fit)
        output_dir: Optional one-off directory override (not persisted)
    

Inputs: activity_id (required), format, output_dir.

download_course_gpxA
Destructive

Download a Garmin Connect course as a GPX file.

    The GPX is rebuilt from the course's track points (lat/lon/elevation)
    and course points (as waypoints); it is not the originally uploaded file.

    Args:
        course_id: ID of the course to download.
        output_path: Optional destination directory (saved as {course_id}.gpx)
            or file path ending in .gpx; any other file path is rejected.
            Defaults to the download_activity_file directory
            (GARMIN_FIT_DOWNLOAD_DIR, then set_fit_download_dir), else
            ./courses/{course_id}.gpx.
    

Inputs: course_id (required), output_path.

download_workoutC
Destructive

Download a workout as a FIT file

    Downloads the workout in FIT format. The binary data cannot be returned
    directly through the MCP interface, but this confirms the workout is available.

    Args:
        workout_id: ID of the workout to download
    

Inputs: workout_id (required).

get_acclimationA
Read-only

Get heat and altitude acclimation status for a given date.

    Garmin tracks how adapted the athlete currently is to training in heat
    and at altitude. heat_acclimation_percent runs 0-100 and decays without
    continued exposure; use it to judge readiness for a warm-weather race.

    heat_trend reports Garmin's own label (e.g. ACCLIMATIZED). The
    previous_* fields hold the prior reading so direction of travel is
    visible without a second call.

    VO2 max is not returned here; use get_training_status or get_vo2max_trend.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_activitiesA
Read-only

Get activities with pagination support.

    Retrieves a paginated list of activities ordered newest-first. Use this
    for browsing through large activity lists when you do not need to filter
    by date range, or as a complement to get_activities_by_date.

    Each activity includes an event_type field. Common values: "race",
    "training", "uncategorized" (no event type set by the user — common for
    Peloton imports and untagged runs). Filter for races with
    event_type == "race" rather than excluding "training", as many non-race
    activities appear as "uncategorized" rather than "training".

    Args:
        start: Starting index (default 0)
        limit: Maximum number of activities to return (default 20, max 100)
    

Inputs: limit, start.

get_activities_by_dateA
Read-only

Get activities between specified dates with pagination support.

    For accounts with large activity histories, broad date ranges can return
    thousands of activities in a single response. Use page and page_size to
    retrieve activities in manageable chunks and avoid "result too large" errors.
    Activities are ordered newest-first.

    Pagination: when has_more is true the response includes next_page — pass
    that value as page on the next call to retrieve the following page. Repeat
    until has_more is false.

    Note: total_count for a date range is not available from the Garmin API
    without fetching all results. Use has_more / next_page to walk pages.

    Each activity includes an event_type field with values such as:
      - "race"          — explicitly tagged as a race by the user
      - "training"      — explicitly tagged as a training activity
      - "uncategorized" — no event type set; common for Peloton imports and
                          untagged outdoor runs. Distinct from "training":
                          filter for races with event_type == "race" rather
                          than excluding "training", since many non-race
                          activities appear as "uncategorized" not "training"
      - field absent    — API returned no eventType for this activity; not
                          observed in practice in any activity back to 2012
                          (oldest activities sampled on this account)

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
        activity_type: Optional activity type filter (e.g., cycling, running, swimming)
        page: Zero-based page number (default 0)
        page_size: Number of activities per page, max 200 (default 100)
    

Inputs: end_date (required), start_date (required), page, page_size, +1 more.

get_activities_fordateC
Read-only

Get activities for a specific date

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_activityA
Read-only

Get detailed information for a single activity.

    Returns a comprehensive summary including timing, distance, heart rate,
    elevation, training effect, and an event_type field. Common event_type
    values: "race", "training", "uncategorized" (no event type set by the
    user). The field is omitted when Garmin returns no eventTypeDTO.

    Args:
        activity_id: ID of the activity to retrieve
    

Inputs: activity_id (required).

get_activity_exercise_setsC
Read-only

Get exercise sets for strength training activities

    Args:
        activity_id: ID of the activity to retrieve exercise sets for
    

Inputs: activity_id (required).

get_activity_fit_dataA
Read-only

Download and parse FIT file for an activity to expose advanced cycling data.

    Returns data not available through the standard REST API, including:
    - DI2 / electronic shifting events with cadence at time of shift, grade at shift,
      gear combinations, shift quality classification, and terrain-grouped shift analysis
    - Cycling dynamics per session and lap: platform center offset (PCO), left/right power
      balance, torque effectiveness, pedal smoothness
    - Variability Index (NP / avg_power) per session and lap
    - Climb detection with VAM (vertical ascent rate), avg power/cadence/HR per climb,
      and W/kg per climb (using the latest Garmin weigh-in on or before the ride,
      up to 90 days back; rider_weight_date says which weigh-in was used)
    - Grade-correlated stats: avg power, cadence, HR broken down by terrain steepness
    - Grade comes from the device's per-record grade field when present; otherwise
      it is derived from altitude and distance (~100 m window). grade_source
      ("device" | "derived") says which
    - HR drift / cardiac drift coefficient (aerobic decoupling for rides ≥60 min)
    - Temperature correlation: avg HR/power in hottest vs. coolest portions of ride
    - Power Duration Curve: best mean maximal power at 5s, 30s, 1min, 5min, 10min, 20min, 60min
    - Optional full per-second time series when include_records=True

    Multisport files (triathlon, duathlon) contain one session per leg. For
    these, the response adds multisport=true and a sessions list with every
    leg; session and the record-based analyses (power curve, climbs, grade,
    HR drift, temperature) describe one leg only — the cycling leg if there
    is exactly one, else the longest — given by analyzed_session_index and
    explained in analysis_note. Laps and records still cover all legs.

    Shift quality:
    - proactive: shifted at 70-100 rpm (ideal cadence range)
    - reactive: shifted below 70 rpm (already grinding before shifting)
    - coasting: shifted at 0 rpm (mid-stop or freewheeling)
    - spun_out: shifted above 100 rpm (waited too long in easy gear)

    Note: DI2 data requires Shimano Di2 / SRAM eTap. Cycling dynamics require a
    compatible power meter (e.g., Garmin Rally, Favero Assioma, PowerTap P1 pedals).

    Args:
        activity_id: Garmin activity ID
        include_records: Include full per-second time series (default False).
                         Warning: adds significant data volume for long rides.
    

Inputs: activity_id (required), include_records.

get_activity_fit_messagesA
Read-only

Retrieve and generically parse an activity's original FIT file.

    This is the source-of-truth endpoint for original device activity data.
    It returns every message and every field emitted by the FIT decoder
    without applying sport-specific curation. Messages remain in file order,
    and each field includes its decoded value plus units and definition
    number when available. Unknown and duplicate fields are retained.

    Garmin Connect edits made after upload may be stored only in Garmin's
    service and are not necessarily written back into the original FIT file.
    This tool intentionally does not merge those service-side edits.

    High-frequency ``record`` messages are counted but omitted by default.
    Other message types occurring more than 100 times are also inventoried
    but omitted from an unfiltered default response. Request those types
    explicitly with message_types. All returned messages are bounded by
    message_offset/message_limit (maximum 5000 per call); follow
    pagination.next_offset until absent to retrieve the full selected stream.

    Use message_types to return only particular FIT message types while
    message_counts still inventories the complete file. For example, a
    strength workout can usually be inspected efficiently with
    ["session", "lap", "set", "exercise_title"]. Message type names are
    case-insensitive and should use FIT/fitparse snake_case names.

    Args:
        activity_id: Garmin activity ID.
        message_types: Optional list of FIT message types to return. Omit to
                       return low-frequency non-record message types.
        include_records: Include the high-frequency record stream (default false).
        message_offset: Zero-based offset within the selected message stream.
        message_limit: Maximum messages returned per call, 1-5000 (default 1000).
    

Inputs: activity_id (required), message_limit, message_types, message_offset, +1 more.

get_activity_gearC
Read-only

Get gear data used for an activity

    Args:
        activity_id: ID of the activity to retrieve gear data for
    

Inputs: activity_id (required).

get_activity_hr_in_timezonesC
Read-only

Get heart rate data in different time zones for an activity

    Args:
        activity_id: ID of the activity to retrieve heart rate time zone data for
    

Inputs: activity_id (required).

get_activity_power_in_timezonesA
Read-only

Get power distribution across training zones for an activity.

    Returns time spent in each power zone with watt thresholds and duration.
    Requires a power meter. Zones are based on the athlete's FTP configured in Garmin Connect.

    Args:
        activity_id: ID of the activity to retrieve power zone data for
    

Inputs: activity_id (required).

get_activity_splitsC
Read-only

Get splits for an activity

    Lap and nested length start_time_gmt timestamps are GMT (UTC).

    Args:
        activity_id: ID of the activity to retrieve splits for
    

Inputs: activity_id (required).

get_activity_split_summariesC
Read-only

Get split summaries for an activity

    Args:
        activity_id: ID of the activity to retrieve split summaries for
    

Inputs: activity_id (required).

get_activity_typed_splitsC
Read-only

Get typed splits for an activity

    Args:
        activity_id: ID of the activity to retrieve typed splits for
    

Inputs: activity_id (required).

get_activity_typesA
Read-only

Get all available activity types

Returns a list of all activity types supported by Garmin Connect, useful for filtering activities by type.

Inputs: no named parameters.

get_activity_weatherA
Read-only

Get weather data for an activity.

    Garmin's weather endpoint returns temperatures in Fahrenheit (from the
    weather-station source) with no unit indicator, regardless of account
    settings. This tool converts them to the account's display unit: metric
    accounts get Celsius, statute_us accounts keep Fahrenheit. The
    temperature_unit field ("F" or "C") states which unit was returned.

    Wind speed, unlike temperature, is already returned in the account's
    display unit (km/h for metric, mph for statute_us), so it is passed
    through unconverted and labeled via the wind_speed_unit field.

    Args:
        activity_id: ID of the activity to retrieve weather data for
    

Inputs: activity_id (required).

get_adhoc_challengesA
Read-only

Get user-created social/group challenges (e.g., step competitions with friends)

    Returns challenges created by users to compete with connections. These are
    different from official Garmin badge challenges.

    Args:
        start: Starting index for pagination (default 0)
        limit: Maximum number of challenges to return (default 20, max 100)
    

Inputs: limit, start.

get_all_day_eventsC
Read-only

Get daily wellness events data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_all_day_stressC
Read-only

Get all-day stress data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_available_badge_challengesA
Read-only

Get official Garmin badge challenges available to join

    Returns monthly/seasonal challenges from Garmin that the user can join.
    These challenges award badges and points upon completion.

    Args:
        start: Starting index for pagination (starts at 1)
        limit: Maximum number of challenges to return (default 20, max 100)
    

Inputs: limit, start.

get_badge_challengesA
Read-only

Get badge challenges the user has completed.

    Returns the completed badge-challenge history and earned dates. For
    challenges still in progress, use get_non_completed_badge_challenges.

    Args:
        start: Starting index for pagination (starts at 1)
        limit: Maximum number of challenges to return (default 20, max 100)
    

Inputs: limit, start.

get_blood_pressureC
Read-only

Get blood pressure data

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_body_batteryC
Read-only

Get body battery data with events

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_body_battery_eventsC
Read-only

Get body battery events data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_body_compositionB
Read-only

Get body composition data for a single date or date range

    Args:
        start_date: Date in YYYY-MM-DD format or start date if end_date provided
        end_date: Optional end date in YYYY-MM-DD format for date range
    

Inputs: start_date (required), end_date.

get_calendar_eventsA
Read-only

Get races and events on the Garmin Connect calendar between two dates

    Returns calendar entries the user added or subscribed to in Garmin
    Connect, such as upcoming races. Use this to answer questions about
    which events or races are scheduled.

    These entries are not returned by get_scheduled_workouts, which covers
    only workouts, nor by get_goals. This is the only tool that exposes
    them.

    Each event reports its distance in meters when Garmin stores one,
    the user's custom goal time in seconds when set, the local start
    time when the organiser published it, and two flags: is_race marks
    the entry as a race rather than a general event, and primary_event
    marks the goal race that an active training plan targets. Goal time
    comes from a per-event detail request.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_course_detailsA
Read-only

Get full details of a Garmin Connect course by ID.

    Returns course metadata, elevation gain/loss, total distance,
    and all custom course waypoints (shops, water, food, campgrounds, hazards).

    Args:
        course_id: ID of the course (from get_courses).
    

Inputs: course_id (required).

get_coursesA
Read-only

List all courses saved on Garmin Connect.

Returns a curated list of courses with id, name, distance, activity type and creation date.

Inputs: no named parameters.

get_custom_foodsA
Read-only

Search or list user's custom foods

    Returns custom foods the user has created. Use the search parameter
    to find existing foods by name before creating duplicates — the
    response includes foodId and servingId needed for log_custom_food.

    For branded catalog foods (FatSecret), use search_foods instead.

    Args:
        search: Search term to filter foods by name (default: list all)
        start: Starting index for pagination (default 0)
        limit: Maximum number of results (default 20)
    

Inputs: limit, start, search.

get_custom_food_serving_unitsA
Read-only

Get available serving units for custom foods

Returns the list of valid serving units (e.g. G, ML, OZ) that can be used when creating custom foods.

Inputs: no named parameters.

get_cycling_ftpB
Read-only

Get the latest cycling Functional Threshold Power (FTP) data.

Returns the most recent cycling FTP estimate available from Garmin.

Inputs: no named parameters.

get_daily_stepsB
Read-only

Get steps data for a date range

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_daily_weigh_insC
Read-only

Get weight measurements for a specific date

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_device_alarmsB
Read-only

Get alarms from all Garmin devices

Returns all configured alarms with their schedules, sounds, and enabled status.

Inputs: no named parameters.

get_device_last_usedB
Read-only

Get information about the last used Garmin device

Inputs: no named parameters.

get_devicesA
Read-only

Get all Garmin devices associated with the user account

Inputs: no named parameters.

get_device_settingsA
Read-only

Get settings for a specific Garmin device

    Returns device configuration including time/date format, units,
    activity tracking settings, and alarm information.

    Args:
        device_id: Device ID (optional; defaults to the most recently used
            device when omitted; can be obtained from get_devices or
            get_device_last_used)
    

Inputs: device_id.

get_device_solar_dataA
Read-only

Get solar data for a specific device

    Returns a per-day summary of solar charging for devices with solar panels
    (e.g., Instinct Solar, Fenix Solar): activity time gained from solar, and
    the average/peak solar utilization and minutes with solar input across the
    day's per-minute readings. Only applicable to solar-capable devices.

    Args:
        device_id: Device ID (can be obtained from get_devices)
        date: Date in YYYY-MM-DD format
    

Inputs: date (required), device_id (required).

get_earned_badgesB
Read-only

Get earned badges for user

Inputs: no named parameters.

get_endurance_scoreC
Read-only

Get endurance score data between dates

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_energy_balanceA
Read-only

Estimate a composition-derived TDEE from logged intake, Garmin's claimed expenditure, and body-composition change over a date range.

    Combines three signals Garmin exposes separately -- mean logged intake
    (nutrition log), mean claimed expenditure (Garmin's total_calories from
    daily stats), and a body-composition trend (weight and body-fat % from
    smart-scale readings) -- into composition_derived_tdee, an estimate
    independent of Garmin's calorie model:
    composition_derived_tdee = mean_intake + implied_deficit, where
    implied_deficit comes from the fitted rate of fat and fat-free mass
    change, using the standard energy-density approximations
    7700 kcal/kg fat and 1800 kcal/kg fat-free mass. These are body
    composition literature estimates, not Garmin-provided or measured
    values -- treat the result as a rough estimate, not a lab measurement.
    difference_kcal_per_day (Garmin's claim minus this estimate) has at
    least two explanations -- Garmin overestimating expenditure, or
    under-logged intake, which is common -- and this tool cannot
    distinguish between them.

    The body-composition trend is fit by least-squares regression across
    every qualifying scale reading in range, not just the first and last --
    an endpoint-to-endpoint difference is fully determined by two
    individual measurements and inherits all of their noise (a 0.5%
    body-fat wobble, well within normal scale repeatability, can swing a
    two-point estimate by over a hundred kcal/day). weight_change_kg,
    fat_mass_change_kg, and lean_mass_change_kg in body_composition are
    all fitted values (the fitted line's value at the last reading's day
    offset minus its value at the first), not raw differences between the
    observed_first_*/observed_last_* fields, which are the actual
    readings for reference/sanity-checking, not what the change figures
    are computed from -- fitted_first_weight_kg/fitted_last_weight_kg are
    also included so fitted_last_weight_kg - fitted_first_weight_kg can be
    checked against weight_change_kg directly.

    implied_deficit_kcal_per_day is the slope of a single regression: for
    each reading, compute -(fat_kg * 7700 + lean_kg * 1800) where
    lean_kg = weight_kg - fat_kg, then fit that value against day offset.
    This is mathematically identical to combining separately-fit fat and
    lean slopes, but its standard error -- implied_deficit_uncertainty_kcal_per_day,
    returned whenever more than 2 readings are used -- is that single
    fit's own residual standard error, which is well-defined and
    reproducible from the raw readings alone (fat_kg and lean_kg are both
    derived from the same weight/body-fat pair per reading, so treating
    their separately-fit slopes' errors as independent and combining them
    after the fact, instead of fitting the combined series directly,
    would not be reproducible from outside without also knowing that
    assumption). Treat a deficit within roughly one standard error of
    zero as indistinguishable from no change.

    Below a minimum span, or when most of the fit's statistical leverage
    sits in one tight cluster of readings taken within about 48 hours of
    each other, the fitted trend is not reliable even with 3+ readings --
    a close, low-noise pair inside that cluster makes the fit look
    precise while the slope is still mostly an extrapolation from that
    cluster to wherever the other reading(s) fall. When this gate fails,
    body_composition is still returned (it's just the fitted line, always
    checkable against the observed readings) but derived is omitted and
    gate_note explains which condition failed. Prefer windows of 3+ weeks
    with several readings spread across them, not clustered at one end.

    Short windows are also dominated by water/glycogen shifts (which
    carry little caloric weight, unlike true lean tissue), which biases
    the fat-free-mass term; see assumptions.note.

    Exclusions applied automatically, matching get_nutrition_summary_between_dates
    and get_stats_range:
    - Intake: days with no logged food (item_count 0) are excluded from
      the mean, not counted as zero. Days with a low but nonzero
      item_count remain included (excluding them requires judgment this
      tool doesn't make unilaterally) but are called out in
      low_item_count_dates so low-confidence days are visible rather than
      silently blended into the mean. A window with many such days (or
      many item_count-0 days) biases composition_derived_tdee downward --
      check days_excluded_unlogged and low_item_count_dates before
      comparing two windows against each other.
    - Expenditure: days with no device data, and the current (partial)
      day, are excluded from the mean.
    - Body composition: only scale readings with both weight and body-fat
      percentage are used (skips weight-only manual entries).

    Needs at least 2 qualifying body-composition readings to derive a
    trend, and to pass the span/leverage gate above to derive a TDEE from
    it. With 0 or 1 readings, returns the intake/expenditure means and
    whatever body composition data exists, but omits the derived TDEE.

    Maximum range: 61 days per call.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_fitnessage_dataA
Read-only

Get fitness age data

    Args:
        date: Date in YYYY-MM-DD format
        details: If True, include component breakdown (BMI, RHR, vigorous activity)
                 with targets and improvement suggestions
    

Inputs: date (required), details.

get_floorsB
Read-only

Get floors climbed data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_full_nameA
Read-only

Get user's full name from profile

Inputs: no named parameters.

get_garmin_coach_workoutsA
Read-only

Get Garmin Coach workouts around the given date

    Returns workouts from the active Garmin Coach/training plan, including
    plan metadata, workout identifiers, dates, sport, duration, completion
    status, rest days, race days, and workout intent when Garmin provides
    them. Adaptive plans expose only Garmin's currently generated window,
    typically the current week; future dates may return no workouts even
    while a plan is active. The count includes rest-day entries.

    Garmin's standalone Daily Suggested Workouts are generated on compatible
    devices. As of July 31, 2026, no supported or known Garmin Connect
    web/API endpoint, including those exposed by this project's
    python-garminconnect dependency, returns the device's upcoming DSW
    schedule. This tool returns Garmin Coach/training-plan workouts and does
    not synthesize device-generated suggestions.

    This is the preferred tool for Garmin Coach requests. The legacy
    get_training_plan_workouts tool returns the same data; do not call both.

    Adaptive Coach plans typically expose workout_uuid; other plan families
    may expose numeric workout_id. Pass whichever identifier is present to
    get_workout_by_id. Rest-day UUIDs may return minimal detail without
    workout segments.

    Args:
        calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)
    

Inputs: calendar_date (required).

get_gearA
Read-only

Get all gear registered with the user account

    Returns complete gear inventory including free-text notes, usage statistics,
    and default activity associations. The notes field is null when unavailable.
    defaults maps each activity type (Garmin typeKey, e.g. "running") to the
    names of its default gear.
    A gear item's stats_error reports a failed usage-statistics request;
    a null total_distance_km means Garmin did not provide a distance.
    No parameters required - user profile is fetched automatically.

    Args:
        include_stats: Include usage statistics for each gear item (default True).
                       Set to False for faster response with large gear collections.
    

Inputs: include_stats.

get_goalsA
Read-only

Get Garmin Connect goals (active, future, or past).

    Reads goals the way Garmin Connect's Goals page does, so named
    distance/time targets (e.g. a monthly cycling mileage goal) are
    included with their progress and remaining amounts. Falls back to
    python-garminconnect's get_goals() if that request returns nothing.

    Args:
        goal_type: Type of goals to retrieve. Options: "active", "future", or "past"
    

Inputs: goal_type.

get_heart_ratesA
Read-only

Get full heart rate time-series data

    Note: This returns detailed 2-minute interval data (~25KB).
    For a compact summary, use get_heart_rates_summary().

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_heart_rates_summaryA
Read-only

Get heart rate summary with essential metrics (lightweight version)

    Returns a compact summary (~500 bytes) instead of full time-series data (~25KB).
    Ideal for daily health checkups and LLM integrations.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_heart_rate_zonesA
Read-only

Get the user's saved heart-rate training-zone configuration.

    Garmin stores a generic DEFAULT profile plus optional sport-specific
    overrides such as RUNNING and CYCLING. With no sport, this returns every
    saved profile; pass a sport key to return just that profile.

    Args:
        sport: Optional Garmin sport key (for example default, running, or
               cycling). "generic" is accepted as an alias for DEFAULT.
    

Inputs: sport.

get_hill_scoreC
Read-only

Get hill score data between dates

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_hrv_dataB
Read-only

Get Heart Rate Variability (HRV) data

    Args:
        date: Date in YYYY-MM-DD format
        return_timeseries: If True, include detailed 5-minute HRV readings (can be large)
    

Inputs: date (required), return_timeseries.

get_hrv_trendA
Read-only

Get HRV (Heart Rate Variability) trend over a date range.

    Returns daily HRV values and weekly rolling averages. Single-day HRV is too noisy
    to act on — use this tool to identify baseline shifts that signal accumulated fatigue
    or recovery. A drop of >10ms from the 7-day baseline warrants reducing training load.

    Recommended range: 7-21 days. Maximum: 30 days.
    Empty days are skipped; a failed daily request returns an error.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_hydration_dataC
Read-only

Get hydration data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_inprogress_virtual_challengesA
Read-only

Get in-progress virtual challenges/expeditions

    Returns virtual challenges (like walking expeditions on famous trails)
    that the user is currently participating in.

    Args:
        start: Starting index for pagination (default 1, must be >= 1;
            garminconnect 0.3.2 rejects 0 for this endpoint)
        limit: Maximum number of challenges to return (default 20, max 100)
    

Inputs: limit, start.

get_lactate_thresholdA
Read-only

Get lactate threshold data

    Returns lactate threshold information, which is the exercise intensity at
    which lactate starts to accumulate in the blood. This is a key metric for
    endurance training.

    Args:
        start_date: Start date in YYYY-MM-DD format (optional; give with
            end_date for history, omit both for latest)
        end_date: End date in YYYY-MM-DD format (optional; give with
            start_date for history, omit both for latest)
    

Inputs: end_date, start_date.

get_lifestyle_logging_dataB
Read-only

Get lifestyle logging data for a specific date

    Returns lifestyle logging data which allows users to track behaviors
    and their impact on health metrics.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_menstrual_calendar_dataA
Read-only

Get menstrual calendar data between specified dates

    Automatically chunks requests longer than 92 days, Garmin's
    server-side limit, and stitches the responses together.
    Identical records spanning a chunk boundary are returned once for list
    and dict-of-list responses. Other payload shapes are returned per chunk.
    
    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_menstrual_data_for_dateC
Read-only

Get menstrual data for a specific date

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_morning_training_readinessA
Read-only

Get morning training readiness score

    Returns the morning training readiness assessment, which evaluates
    recovery status and readiness to train based on overnight metrics.
    Fields match one get_training_readiness entry (the snapshot taken
    right after waking).

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_non_completed_badge_challengesA
Read-only

Get badge challenges currently in progress (not yet completed)

    Returns active challenges the user has joined but hasn't completed yet.
    Useful for tracking current progress toward badge goals.

    Args:
        start: Starting index for pagination (starts at 1)
        limit: Maximum number of challenges to return (default 20, max 100)
    

Inputs: limit, start.

get_nutrition_daily_food_logA
Read-only

Get daily food consumption records for a date

    Returns food items logged throughout the day including calories,
    macronutrients, and meal associations.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_nutrition_daily_mealsA
Read-only

Get daily meal summaries for a date

    Returns meal-level summaries (breakfast, lunch, dinner, snacks)
    with nutritional totals for each meal. Each meal includes a mealId
    needed for logging food items to that meal.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_nutrition_daily_settingsB
Read-only

Get nutrition plan/settings for a date

    Returns the user's nutrition goals and targets including
    calorie targets, macronutrient goals, and plan configuration.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_nutrition_summary_between_datesA
Read-only

Get per-day nutrition totals for every day in a date range.

    Returns one lightweight entry per day (date, calories, carbs, protein,
    fat, item_count) instead of the full per-item food log that
    get_nutrition_daily_food_log returns for a single date. Use this for
    multi-day intake analysis (e.g. mean intake for a TDEE estimate)
    instead of calling get_nutrition_daily_food_log once per day.

    item_count is the number of logged food items that day. A day with
    item_count == 0 has no logged food at all, and a low but nonzero
    item_count may mean only part of the day was logged (e.g. breakfast
    only). Both cases read as low intake in the totals alone -- exclude
    low-item_count days explicitly before averaging intake or deriving
    TDEE; don't infer "unlogged" from a low calorie total.

    Maximum range: 61 days per call (Garmin's own limit for this endpoint).

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_personal_recordC
Read-only

Get personal records for user

Inputs: no named parameters.

get_power_duration_curveA
Read-only

Get season-best Power Duration Curve across recent activities.

    Downloads FIT files for recent activities of the requested type and computes best mean maximal
    power at each standard duration. Returns season bests with which activity and date
    each best came from.

    Durations: 5s (sprint), 30s, 1min, 5min (VO2 max proxy), 10min, 20min (FTP proxy), 60min

    Use the 20-minute best × 0.95 as a strong FTP estimate without a formal test.

    Warning: downloads multiple FIT files — may take 30-60 seconds for 20 activities.

    Args:
        num_activities: Number of recent activities matching activity_type to request
                        (default 20, max 50)
        activity_type: Activity type to filter (default "cycling")
    

Inputs: activity_type, num_activities.

get_pregnancy_summaryC
Read-only

Get pregnancy summary data

Inputs: no named parameters.

get_primary_training_deviceA
Read-only

Get information about the primary training device

Returns details about the device designated as primary for training metrics, along with other wearable devices on the account.

Inputs: no named parameters.

get_progress_summary_between_datesA
Read-only

Get progress summary for a metric between dates

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
        metric: Metric to get progress for (e.g., "elevationGain", "duration", "distance", "movingDuration", "calories")

    Note: "calories" values are returned in kcal. Garmin's underlying
    endpoint stores this metric pre-scaled by ~4.19; this tool undoes
    that scaling before returning.
    

Inputs: metric (required), end_date (required), start_date (required).

get_race_predictionsB
Read-only

Get predicted race times based on current fitness level

Returns Garmin's predictions for 5K, 10K, half marathon, and marathon finish times based on the user's recent training data and VO2 max.

Inputs: no named parameters.

get_recovery_time_remainingA
Read-only

Get remaining recovery time in hours for a day.

    This is the Firstbeat recovery clock shown on-device, distinct from
    Training Readiness score (missing on some devices such as Forerunner 255)
    and from Training Status ACWR. Training Readiness values are snapshots:
    remaining_hours and state describe the snapshot at as_of (Garmin's local
    timestamp when available), not a live countdown. remaining_hours_at_snapshot
    retains the same value explicitly. For today only, when snapshots are
    absent, the tool estimates remaining recovery by decaying recent activity
    assignments and reports the estimate's as_of time. Today uses the server's
    local date. Request failures are reported as errors, or source_errors when
    another source supplies usable data.

    Args:
        date: Date in YYYY-MM-DD format. Defaults to today.
    

Inputs: date.

get_respiration_dataA
Read-only

Get full respiration time-series data

    Note: This returns detailed interval data (~20KB).
    For a compact summary, use get_respiration_summary().

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_respiration_summaryA
Read-only

Get respiration summary with essential metrics (lightweight version)

    Returns a compact summary (~300 bytes) instead of full time-series data (~20KB).

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_respiration_trendA
Read-only

Get overnight respiration rate trend over a date range.

    Elevated resting respiration rate (compared to personal baseline) is an early
    warning sign for overreaching, illness, or poor recovery. Use this alongside HRV
    trend for a complete recovery picture.

    Recommended range: 7-21 days. Maximum: 30 days.
    Empty days are skipped; a failed daily request returns an error.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_rhr_dayC
Read-only

Get resting heart rate data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_running_toleranceA
Read-only

Get Running Tolerance for a single day.

    Returns Garmin's running load capacity model: how much running load the
    athlete can currently absorb (tolerance), the intensity-adjusted load
    their recent runs have produced (acute load), and the raw distance behind
    that load. All three are expressed in km so they're directly comparable —
    `load_ratio` (acute_load_km / distance_km) quantifies how much intensity
    is inflating the cost of each kilometer run.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_running_tolerance_trendA
Read-only

Get Running Tolerance trend over a date range.

    Running Tolerance moves slowly — its value is in the trajectory, not any
    single day. Returns, per period: tolerance_km (current load capacity),
    acute_load_km (intensity-adjusted load), distance_km (actual distance
    run), and load_ratio (acute_load_km / distance_km — how much intensity
    inflates the cost of each kilometer). Weekly aggregation (default) gives
    a compact multi-month view; daily gives day-to-day resolution for a
    shorter window.

    Recommended range: 4-12 weeks. Maximum: 90 days for daily aggregation,
    366 days for weekly (this endpoint returns the whole range in one call,
    so the limit protects output size, not request volume).

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
        aggregation: "daily" or "weekly" (default "weekly")
    

Inputs: end_date (required), start_date (required), aggregation.

get_scheduled_workoutsA
Read-only

Get scheduled workouts between two dates with curated summary list

    Returns workouts that have been scheduled on the Garmin Connect calendar,
    including their scheduled dates and completion status.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_sleep_dataA
Read-only

Get full sleep data with all details

    Note: This returns detailed sleep data (~50KB).
    For a compact summary, use get_sleep_summary().

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_sleep_summaryA
Read-only

Get sleep summary with only essential metrics (lightweight version)

    This endpoint returns a compact summary of sleep data (~350 bytes) instead of
    the full granular data (~50KB). Ideal for daily health checkups and LLM integrations
    where the full time-series data would overwhelm the context window.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_sleep_summary_rangeA
Read-only

Get lightweight sleep summaries for every night in a date range.

    Returns the same curated metrics as get_sleep_summary (sleep score, duration,
    sleep stages, HRV, resting HR, etc.) for each night between start_date and
    end_date, inclusive. Use this instead of calling get_sleep_summary once per
    night when analyzing sleep trends over weeks or months.

    Note: Garmin Connect does not expose a native range endpoint for sleep, so
    this makes one request per night internally. Recommended range: up to a
    few weeks for quick checks. Maximum: 90 nights per call.
    Empty nights are skipped; a failed request stops the range and returns
    an error identifying the failed date.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_spo2_dataC
Read-only

Get SpO2 (blood oxygen) data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_statsA
Read-only

Get daily activity stats with curated essential metrics

    Returns a summary of daily health and activity data including steps,
    calories, heart rate, stress, body battery, and sleep metrics.

    Note: bmr_calories is Garmin's bmrKilocalories field -- per Garmin's
    own documentation this is RMR (BMR plus sedentary-to-light movement),
    not true basal metabolic rate. For the current date, all calorie and
    duration fields are a partial-day accumulator (elapsed hours so far),
    not a full-day total.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_stats_and_bodyC
Read-only

Get stats and body composition data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_stats_rangeA
Read-only

Get lightweight per-day calorie and step totals for a date range.

    Returns total/active/resting calories and steps for each day between
    start_date and end_date, inclusive, instead of the full get_stats
    payload per day. Use this for multi-day analysis (e.g. comparing
    measured intake/expenditure against Garmin's calorie model) instead
    of calling get_stats once per day.

    resting_calories is Garmin's bmrKilocalories field -- per Garmin's
    own documentation this is RMR (BMR plus sedentary-to-light movement),
    not true basal metabolic rate.

    is_partial is true for the current date, whose accumulator only
    covers elapsed hours so far -- treating it as a full day will
    overstate a mean. Days with no device data (e.g. before the account
    existed, or future dates within the range) return has_data: false
    and null values rather than zeros, so a missing day never silently
    enters an average as zero.

    Maximum range: 28 days per call (Garmin's own limit for this endpoint).

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_steps_dataA
Read-only

Get detailed steps data with 15-minute intervals

    Note: This returns full interval data (~14KB). For a compact summary,
    use get_stats() which includes total_steps.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_stress_dataA
Read-only

Get full stress time-series data

    Note: This returns detailed interval data (~35KB) including body battery.
    For a compact summary, use get_stress_summary().

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_stress_summaryA
Read-only

Get stress summary with essential metrics (lightweight version)

    Returns a compact summary (~400 bytes) instead of full time-series data (~35KB).
    Ideal for daily health checkups and LLM integrations.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_training_effectB
Read-only

Get training effect data for a specific activity.

    Uses activity details first. If Garmin returns HTTP 403 for that
    endpoint (seen on valid, recent activities), falls back to activity
    list search, which still includes aerobic/anaerobic training effect.

    Args:
        activity_id: ID of the activity to retrieve training effect for
    

Inputs: activity_id (required).

get_training_load_balanceA
Read-only

Get Garmin's Load Focus — the distribution of the trailing-month training load across Aerobic Low, Aerobic High, and Anaerobic intensity bands, plus the system's feedback phrase (e.g. AEROBIC_HIGH_SHORTAGE, BALANCED, ANAEROBIC_SHORTAGE).

    Use this to assess whether the athlete's training mix is balanced or
    deficient in a particular intensity band. Each band reports its load
    alongside Garmin's target range; a `status` of "below", "within", or
    "above" is computed from the load relative to that range.

    Garmin reports Load Focus per device. The primary activity tracker's
    record is used when it can be identified; `load_device_id` and
    `load_device_name` say which device the numbers came from.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_training_load_trendA
Read-only

Get Garmin's daily acute and chronic training load over a date range.

    Returns, per day, Garmin's acute load (`atl`, the 7-day load), chronic load (`ctl`), their
    difference (`tsb` = ctl - atl), and Garmin's Acute:Chronic Workload Ratio (`acwr`,
    `acwr_status`). These are Garmin's dailyTrainingLoadAcute/Chronic values, not TrainingPeaks
    CTL/ATL: they are on Garmin's weekly load scale, so `tsb` is not comparable to TrainingPeaks
    TSB and TSB form thresholds do not apply. Use `acwr`/`acwr_status` (and the optimal chronic
    load range) to judge whether load is building steadily or spiking.

    Recommended range: 4-8 weeks. Maximum: 90 days.
    Empty days are skipped; a failed daily request returns an error.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_training_plan_workoutsA
Read-only

Compatibility alias for get_garmin_coach_workouts

    Prefer get_garmin_coach_workouts for new requests. This legacy tool
    returns the same Garmin Coach/training-plan data; do not call both for
    one request. Adaptive plans expose only Garmin's currently generated
    window, typically the current week; future dates may return no workouts
    even while a plan is active.

    Adaptive training plans typically expose workout_uuid; other plan
    families may expose numeric workout_id. Pass whichever identifier is
    present to get_workout_by_id. The returned count includes rest days.

    Args:
        calendar_date: Reference date in YYYY-MM-DD format (returns week's workouts)
    

Inputs: calendar_date (required).

get_training_readinessB
Read-only

Get training readiness data with curated metrics

    Returns training readiness score and contributing factors.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_training_statusB
Read-only

Get training status with curated metrics

    Returns comprehensive training status including load, VO2 max, recovery,
    and training readiness indicators.

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_unit_systemB
Read-only

Get user's preferred unit system from profile

Inputs: no named parameters.

get_user_profileC
Read-only

Get user profile information

Inputs: no named parameters.

get_userprofile_settingsC
Read-only

Get user profile settings

Inputs: no named parameters.

get_user_summaryC
Read-only

Get user summary data (compatible with garminconnect-ha)

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

get_vo2max_trendA
Read-only

Get VO2 max trend over a date range.

    Returns daily VO2 max estimates from Garmin's FirstBeat algorithm. Use this to track
    whether training is producing fitness gains over weeks or months. Flat or declining
    VO2 max over 4+ weeks suggests insufficient training stimulus or overreaching.

    Note: VO2 max estimates are smoothed and update gradually — daily changes of <0.5
    are within normal noise. Focus on the 4-6 week trend direction.

    Garmin records a new VO2 max value only on days with a recompute (after an
    activity). Days in between carry the last known value forward and are marked
    with "carried_forward": true, matching the trend chart in Garmin Connect.
    Dated status values retain their measurement date. data_points counts
    displayed days, including carried-forward values.

    If historical values are unavailable, the current profile estimate is returned
    separately and is not represented as a historical trend point.
    Endpoint-specific failures remain visible in request_errors when a
    fallback succeeds. Authentication, rate-limit, and connection failures
    stop the request.

    Recommended range: 4-12 weeks. Maximum: 90 days.

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_weekly_intensity_minutesA
Read-only

Get weekly intensity minutes data aggregates

    Returns weekly intensity minutes (moderate and vigorous) for the specified
    number of weeks ending at end_date. total_minutes counts each vigorous
    minute twice (moderate + 2 x vigorous), as Garmin does, so it is the
    figure to compare against weekly_goal; moderate_minutes and
    vigorous_minutes are the raw, unweighted minutes.

    Args:
        end_date: End date in YYYY-MM-DD format
        weeks: Number of weeks to fetch (default 4, max 52)
    

Inputs: end_date (required), weeks.

get_weekly_stepsA
Read-only

Get weekly step data aggregates

    Returns weekly step totals for the specified number of weeks ending at end_date.

    Args:
        end_date: End date in YYYY-MM-DD format
        weeks: Number of weeks to fetch (default 4, max 52)
    

Inputs: end_date (required), weeks.

get_weekly_stressB
Read-only

Get weekly stress data aggregates

    Returns weekly stress values for the specified number of weeks ending at end_date.

    Args:
        end_date: End date in YYYY-MM-DD format
        weeks: Number of weeks to fetch (default 4, max 52)
    

Inputs: end_date (required), weeks.

get_weigh_insC
Read-only

Get weight measurements between specified dates

    Args:
        start_date: Start date in YYYY-MM-DD format
        end_date: End date in YYYY-MM-DD format
    

Inputs: end_date (required), start_date (required).

get_workout_by_idA
Read-only

Get detailed information for a specific workout

    Returns workout details including segments and step structure.

    Accepts either:
    - Numeric workout ID (from get_workouts, get_scheduled_workouts, or
      training-plan families that expose workout_id)
    - Workout UUID (from adaptive Garmin Coach/training-plan workouts)

    Rest-day UUIDs can resolve to a minimal record without a workout name
    or segments.

    Pace target values are speeds in meters per second. target_value_low
    and target_value_high preserve Garmin's targetValueOne/targetValueTwo
    order; they are not sorted by magnitude.

    Args:
        workout_id: Workout ID (numeric) or UUID (for training plan workouts)
        raw: Return Garmin's full workout JSON (the DTO format upload_workout
            describes) instead of the simplified summary, which leaves fields out.
    

Inputs: workout_id (required), raw.

get_workoutsA
Read-only

Get all workouts with curated summary list

    Returns a count and list of workout summaries with essential metadata only.
    For detailed workout information including segments, use get_workout_by_id.
    

Inputs: no named parameters.

log_custom_foodA

Log a food item to a meal on a date

    Adds a food entry to the nutrition log. The meal is determined
    automatically by matching meal_time against each meal's
    startTime/endTime window; falls back to SNACKS if no window matches.

    Food sources:
      - "GARMIN" (default): user's custom food library. Use
        get_custom_foods to find food_id and serving_id.
      - "FATSECRET": branded/catalog food from FatSecret. Use
        search_foods to find food_id and serving_id. Pass the source
        value from the search_foods result (e.g. "FATSECRET").

    Garmin custom food IDs are 32-char hex UUIDs; FatSecret IDs are
    numeric strings (e.g. "4132350"). Passing the wrong source for a
    given food_id returns a 400 from Garmin.

    Args:
        meal_date: Date in YYYY-MM-DD format
        meal_time: Time in HH:MM:SS format (e.g. "12:30:00", account timezone)
        food_id: Food ID from get_custom_foods (GARMIN) or search_foods (FATSECRET)
        serving_id: Serving ID from get_custom_foods or search_foods
        serving_qty: Number of servings (default 1)
        source: Food namespace — "GARMIN" (default) or "FATSECRET"
    

Inputs: food_id (required), meal_date (required), meal_time (required), serving_id (required), +2 more.

log_foodA

Quick-add a food entry with macro values to the nutrition log

    Logs food directly by name and macros without requiring a food ID.
    Uses Garmin's Quick Add feature. The meal is determined automatically
    by matching meal_time against each meal's startTime/endTime window;
    falls back to SNACKS if no window matches.

    Args:
        meal_date: Date in YYYY-MM-DD format
        name: Display name for the food entry
        calories: Calories (kcal)
        carbs: Carbohydrates in grams
        protein: Protein in grams
        fat: Fat in grams
        meal_time: Time in HH:MM:SS format (account timezone)
    

Inputs: fat (required), name (required), carbs (required), protein (required), +3 more.

push_workout_to_deviceA

Send a workout from the workout library to a Garmin device

    Queues the workout in Garmin Connect's device message queue, the same
    as "Send to Device" in the Garmin Connect app. The watch picks it up
    at its next sync with Garmin Connect (phone app or Wi-Fi), so it does
    not appear on the watch immediately. Scheduling a workout does not
    need this: scheduled workouts reach the watch's calendar on their own.

    Each call queues another copy, so do not push the same workout twice.

    Args:
        workout_id: ID of the workout to send (from get_workouts or upload_workout)
        device_id: Device ID (optional; defaults to the most recently used
            device; can be obtained from get_devices or get_device_last_used)
    

Inputs: workout_id (required), device_id.

remove_gear_from_activityB
Destructive

Remove gear association from an activity

    Unlinks a specific piece of gear from an activity.

    Args:
        activity_id: ID of the activity
        gear_uuid: UUID of the gear to remove
    

Inputs: gear_uuid (required), activity_id (required).

request_reloadC

Request reload of epoch data

    Args:
        date: Date in YYYY-MM-DD format
    

Inputs: date (required).

reschedule_workoutA
DestructiveIdempotent

Move a scheduled workout to another date on the Garmin Connect calendar

    Moves the existing calendar entry in place, so its id stays the same
    and no duplicate entry is created. Prefer this over unschedule +
    schedule. Safe to repeat: moving an entry to the date it is already
    on changes nothing.

    IMPORTANT: scheduled_workout_id is the calendar-entry id, which is
    different from the workout's id. Get it from get_scheduled_workouts
    (the "scheduled_workout_id" field), not from get_workouts.

    Args:
        scheduled_workout_id: Calendar-entry id from get_scheduled_workouts
        calendar_date: New date in YYYY-MM-DD format
    

Inputs: calendar_date (required), scheduled_workout_id (required).

schedule_weekA
Idempotent

Schedule a list of workouts for the week in a single call.

    Idempotent: if a workout is already scheduled for that date, it is
    reported as already scheduled and the POST is skipped (avoids
    duplicating calendar entries).

    Each entry is handled on its own: an invalid or failing entry is
    reported with status "failed" or "error" and the rest still run.
    A successful entry includes scheduled_workout_id when Garmin returns
    the calendar-entry ID; pass it to unschedule_workout to remove the entry.

    Args:
        week: List of dicts with keys: date (YYYY-MM-DD), workout_id (int)
    

Inputs: week (required).

schedule_workoutA
Idempotent

Schedule a workout to a specific calendar date

    This adds an existing workout from your Garmin workout library
    to your Garmin Connect calendar on the specified date.

    Idempotent: if the workout is already scheduled for that date, this
    is a no-op that reports success without creating a duplicate entry.

    Args:
        workout_id: ID of the workout to schedule (get IDs from get_workouts)
        calendar_date: Date to schedule the workout in YYYY-MM-DD format
    

Inputs: workout_id (required), calendar_date (required).

schedule_workoutsA

Schedule multiple workouts to specific calendar dates

    This adds workouts to your Garmin Connect calendar in a single call.
    Each item can either reference an existing workout by ID, or provide
    inline workout_data to upload-and-schedule in one step.

    Args:
        schedules: List of workout schedules, each with:
            - calendar_date (str): Date to schedule the workout in YYYY-MM-DD format (required)
            - workout_id (int): ID of an existing workout to schedule (required unless workout_data is provided)
            - workout_data (dict): Inline workout JSON to upload first, then schedule (optional).
              When provided, workout_id is not required. Uses the same structure and
              target-value rules as upload_workout; pace targets are in m/s, not
              min/km (5:00/km = 3.333 m/s).

    Examples:
        Schedule existing workouts by ID:
        [{"workout_id": 123456, "calendar_date": "2024-01-15"},
         {"workout_id": 789012, "calendar_date": "2024-01-17"}]

        Upload and schedule inline:
        [{"calendar_date": "2024-01-15", "workout_data": {"workoutName": "Easy Run", ...}},
         {"workout_id": 789012, "calendar_date": "2024-01-17"}]
    

Inputs: schedules (required).

search_foodsA
Read-only

Search Garmin's general food catalog (FatSecret + Garmin custom foods)

    Searches across the entire food catalog including FatSecret-sourced
    branded and generic foods, not just the user's Garmin custom foods.
    Use this to find branded packaged foods by name before logging them.

    Returns food_id, source, name, brand, and all available servings with
    macros. The source field ("FATSECRET" or "GARMIN") and food_id together
    identify the right routing for log_custom_food — pass both to
    log_custom_food's food_id and source parameters respectively.

    For the user's own custom foods only, use get_custom_foods instead.

    Args:
        query: Food name or brand to search for (e.g. "Cheerios", "Greek yogurt")
        start: Starting index for pagination (default 0)
        limit: Maximum number of results per page (default 20)
    

Inputs: query (required), limit, start.

set_activity_descriptionA
Destructive

Set or update the free-text description (notes) of an activity.

    This is the notes field shown on the activity page — useful for
    recording how a session felt, kit used, conditions, niggles, etc.
    Pass an empty string to clear an existing description.

    Args:
        activity_id: ID of the activity to update
        description: New description text (empty string clears it).
            Max 2000 characters; Garmin rejects longer.
            Emoji and other non-BMP characters count as two.
    

Inputs: activity_id (required), description (required).

set_activity_event_typeB
Destructive

Set the event type of an activity.

    Event type categorises the activity's purpose. Valid keys:
    race, recreation, specialEvent, training, transportation, touring,
    geocaching, fitness, uncategorized.

    Args:
        activity_id: ID of the activity to update
        event_type: Target event type key (e.g. 'race', 'training')
    

Inputs: event_type (required), activity_id (required).

set_activity_exercise_setsA
Destructive

Replace the exercise sets on a strength (or other rep-counting) activity.

    Writes Garmin's structured per-set data, the same grid the Garmin Connect
    "Edit sets" screen saves, so the sets feed Garmin's exercise history,
    volume and muscle-map charts. This OVERWRITES every existing set,
    including watch-detected sets and their recorded timing; to keep some,
    read them with get_activity_exercise_sets and include them in the list.

    When the watch already recorded the right sets but misidentified the
    exercises, pass keep_timing=True: the existing sets keep their start
    times, durations and rest periods, and only the exercise, reps and
    weight are replaced, in order. The number of sets must match the
    activity's recorded active sets, and duration_seconds/rest_seconds are
    ignored.

    Exercises must use Garmin's own keys. category is an exercise category
    (e.g. DEADLIFT, BENCH_PRESS, PULL_UP, SQUAT) and exercise_name an
    exercise within it (e.g. BARBELL_DEADLIFT, ROMANIAN_DEADLIFT). Garmin
    rejects anything else with "Invalid Category" or "Invalid Sub-Category",
    and rejects the whole request, so a typo leaves the activity unchanged.
    Valid keys, grouped by category, are in
    https://connect.garmin.com/web-data/exercises/Exercises.json

    Args:
        activity_id: ID of the activity to update
        sets: Active sets in the order performed. Each is a dict with:
            category (required): Garmin exercise category key
            exercise_name: Garmin exercise key within the category; omit to
                record just the category
            reps: Repetition count; omit for timed exercises
            weight_kg or weight_lb: Load lifted; omit for bodyweight
            duration_seconds: Time under work for the set
            rest_seconds: Rest after this set, recorded as a REST set
        keep_timing: Keep the recorded set timing and rest periods,
            replacing only exercise, reps and weight (default False)
    

Inputs: sets (required), activity_id (required), keep_timing.

set_activity_feelB
Destructive

Set how an activity felt ('How did you feel?').

    Mirrors Garmin Connect's 5-point feel rating, stored as one of:
      0   = very tired / poor
      25  = tired
      50  = normal
      75  = good
      100 = strong
    Higher is better.

    Args:
        activity_id: ID of the activity to update
        feel: One of 0, 25, 50, 75, 100
    

Inputs: feel (required), activity_id (required).

set_activity_nameB
Destructive

Set or update the name of an activity.

    Args:
        activity_id: ID of the activity to update
        activity_name: New activity name. Max 200 characters; Garmin rejects longer.
    

Inputs: activity_id (required), activity_name (required).

set_activity_typeA
Destructive

Change the activity type (sport) of an activity.

    Useful for reclassifying a mislabelled activity, e.g. flipping a run
    logged as 'trail_running' to 'running', or a 'treadmill_running' walk to
    'treadmill_walking'. Call get_activity_types to see all valid type keys.

    Args:
        activity_id: ID of the activity to update
        type_key: Target activity type key (e.g. 'running', 'trail_running',
            'treadmill_running', 'cycling', 'lap_swimming')
    

Inputs: type_key (required), activity_id (required).

set_blood_pressureC

Set blood pressure values

    Args:
        systolic: Systolic pressure (top number)
        diastolic: Diastolic pressure (bottom number)
        pulse: Pulse rate
        notes: Optional notes
    

Inputs: pulse (required), systolic (required), diastolic (required), notes.

set_fit_download_dirA

Set and persist the default directory for downloaded activity files.

    Stores the absolute path in a small JSON config file
    (~/.garminconnect_fit_config.json, overridable via GARMIN_FIT_CONFIG) so
    download_activity_file can save files without asking again.

    Args:
        path: Directory where activity files (.fit/.gpx/.tcx/.csv) are saved.
              Pass the current working directory to keep files where the
              server runs.
    

Inputs: path (required).

set_heart_rate_zonesA
Destructive

Set an account-level heart-rate training-zone configuration for one sport.

    WARNING: This mutates the user's Garmin Connect account configuration.
    Garmin stores zones per sport, so DEFAULT (the generic fallback),
    RUNNING, CYCLING, and other sport profiles are independent. Only the
    requested sport is written; omitted values are read from that sport's
    current configuration and preserved.

    This change affects future activity recording and zone-based training.
    It does NOT retroactively re-slice already-recorded activities: their
    heart-rate zone boundaries were baked in when those activities were
    recorded.

    The calculation method may be max_hr (% maximum heart rate), hrr or
    karvonen (% heart-rate reserve), lthr (% lactate-threshold heart rate),
    or custom_bpm. Manual zone_boundaries are only accepted with the
    custom_bpm method. Garmin's API does not persist a separate CUSTOM enum:
    direct-BPM zones are sent and read back with trainingMethod=HR_MAX while
    the explicit zone floors remain authoritative.
    Changing the method or reference heart rates preserves the existing
    zone floors; this tool does not calculate new percentage-based floors.

    The tool performs a read-modify-write and then re-fetches the requested
    sport. Its result is the configuration Garmin actually saved, not the
    request payload. If verification fails after Garmin accepts the write,
    it reports success with write_committed=true, a confirmation_error, and
    the submitted_configuration. Re-read the profile before another update.

    Args:
        sport: Garmin sport key, e.g. default/generic, running, or cycling.
        max_hr: Maximum heart rate in BPM.
        resting_hr: Resting heart rate in BPM. Supplying it disables Garmin's
                    resting-HR auto-update for this zone profile.
        lactate_threshold_hr: Lactate-threshold heart rate (LTHR) in BPM.
        calculation_method: max_hr, hrr/karvonen, lthr, or custom_bpm.
        zone_boundaries: Five strictly increasing BPM floors [Z1, Z2, Z3,
                         Z4, Z5]. Every floor must be at most max_hr.
    

Inputs: sport (required), max_hr, resting_hr, zone_boundaries, +2 more.

set_nutrition_daily_settingsA
Destructive

Update daily nutrition goals (calorie target and macronutrient targets).

    Reads the current settings for the date, applies the supplied overrides,
    and writes the merged result back.  Only the fields you provide are
    changed; omitted fields keep their existing values.

    Macro arguments retain their existing names and are passed through to
    Garmin's macroGoals without unit conversion. The endpoint's macro units
    have not been independently verified. Returned goals come from Garmin's
    response, or a settings read-back when the update has no response body.

    Args:
        date: Date in YYYY-MM-DD format (settings are typically set once and
              inherited across days, but Garmin accepts per-day overrides)
        calorie_goal: Daily calorie target in kcal
        carbs_grams: Daily carbohydrate target in grams
        fat_grams: Daily fat target in grams
        protein_grams: Daily protein target in grams
        target_date: Optional new target date (YYYY-MM-DD) for the weight
              goal that this endpoint carries. Only needed when the stored
              target date has already passed, which otherwise makes Garmin
              reject the update; must be after `date`.
    

Inputs: date (required), fat_grams, carbs_grams, target_date, +2 more.

set_perceived_effortA
Destructive

Set the perceived effort (RPE) for an activity.

    Mirrors Garmin Connect's 'Perceived Effort' rating on a 0-10 scale,
    where 0 clears the rating. Internally Garmin stores this multiplied by
    10 (so RPE 7 is stored as 70); this tool handles the conversion.

    Args:
        activity_id: ID of the activity to update
        rpe: Perceived effort from 0 to 10 (0 clears the rating)
    

Inputs: rpe (required), activity_id (required).

unschedule_workoutA
Destructive

Remove a scheduled workout from the Garmin Connect calendar

    Deletes a calendar entry without deleting the underlying workout
    template — the workout stays in your library and can be re-scheduled.

    IMPORTANT: scheduled_workout_id is the calendar-entry id, which is
    different from the workout's id. Get it from get_scheduled_workouts
    (the "scheduled_workout_id" field), not from get_workouts.

    Note: the scheduled-workouts listing is an eventually-consistent index.
    If you just scheduled this workout, allow a moment before unscheduling
    so the id is available.

    Args:
        scheduled_workout_id: Calendar-entry id from get_scheduled_workouts
    

Inputs: scheduled_workout_id (required).

unschedule_workoutsA
Destructive

Remove multiple scheduled workouts from the Garmin Connect calendar

    Deletes multiple calendar entries in a single call. The underlying
    workout templates are left intact in your library.

    IMPORTANT: each id is a calendar-entry id (the "scheduled_workout_id"
    field from get_scheduled_workouts), not a workout id.

    Args:
        scheduled_workout_ids: List of calendar-entry ids from get_scheduled_workouts
    

Inputs: scheduled_workout_ids (required).

update_custom_foodA
Destructive

Update an existing custom food in the user's Garmin nutrition library

    Fetches the food's current record (by food_id, so renaming is safe)
    before writing so that omitted optional fields (brand, carbs, protein,
    fat, micros, etc.) preserve their existing values rather than being
    cleared. Only the fields you explicitly pass are changed; everything
    else is carried forward from the current record.

    Garmin replaces the whole record on update. If the current record
    cannot be read, the update is refused unless serving_unit and
    number_of_units are given; the call then replaces the record in full,
    and any brand or nutrient you omit is cleared.

    Only future logs see the change. Each food-log entry stores its own
    copy of the food's nutrition from when it was logged, so entries
    already logged, and those days' summaries, keep the old values. To
    correct a past day, delete_food_log each affected entry and log it
    again after the update.

    All nutrient amounts are ABSOLUTE values per serving, not %DV.
    Nutrition labels often print %DV for calcium/iron/vitamin D —
    convert to absolute units before passing.

    Use get_custom_foods first to find the foodId and servingId.

    Args:
        food_id: ID of the custom food to update (from get_custom_foods)
        serving_id: Serving ID of the food (from get_custom_foods)
        food_name: Name of the custom food
        calories: Calories per serving
        serving_unit: Unit for serving size (e.g. "G", "ML", "OZ");
            omit to preserve the existing value
        number_of_units: Serving size in the specified unit;
            omit to preserve the existing value
        brand_name: Brand or vendor name; omit to preserve the existing value
        carbs: Carbohydrates in grams per serving
        protein: Protein in grams per serving
        fat: Total fat in grams per serving
        fiber: Fiber in grams per serving
        sugar: Sugar in grams per serving
        saturated_fat: Saturated fat in grams per serving
        sodium: Sodium in mg per serving
        cholesterol: Cholesterol in mg per serving
        potassium: Potassium in mg per serving
        trans_fat: Trans fat in grams per serving
        calcium: Calcium in mg per serving (NOT %DV)
        iron: Iron in mg per serving (NOT %DV)
        vitamin_d: Vitamin D in mcg per serving (NOT %DV)
    

Inputs: food_id (required), calories (required), food_name (required), serving_id (required), +16 more.

upload_courseA

Upload a GPX file as a Garmin Connect Course.

    The course can then be loaded onto the watch (sync or "Send to Device")
    and used as a navigation course or to build a PacePro strategy.

    Args:
        gpx_path: Absolute path to the .gpx file on disk.
        course_name: Override the course name. Defaults to the name parsed
            from the GPX file. Max 128 characters; Garmin rejects longer.
        activity_type: One of running, cycling, hiking, walking, trail_running,
            mountain_biking, road_biking, gravel_cycling. Defaults to running.
        description: Optional description shown on the course detail page.
            Max 512 characters; Garmin rejects longer.
    

Inputs: gpx_path (required), course_name, description, activity_type.

upload_workoutA

Upload a workout from JSON data

    Creates a new workout in Garmin Connect from structured workout data.

    IMPORTANT: Step types must use Garmin's DTO format:
    - Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)
    - Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations.
      Always include endCondition with conditionTypeId 7 and conditionTypeKey
      "iterations"; omitting conditionTypeId causes the API to silently corrupt
      the repeat count.
    - stepOrder is one depth-first counter over the whole workout: a repeat
      group takes the next number and its nested steps continue from there
      (group 2, children 3 and 4, cooldown 5). Do not restart at 1 inside a group.

    IMPORTANT: Heart rate targets come in two forms:
    - Named zone (e.g. Zone 2): set targetType to "heart.rate.zone" and use "zoneNumber" (1-5).
      Do NOT put the zone number in targetValueOne.
    - Custom HR range (e.g. 105-143 bpm): set targetType to "heart.rate.zone" and use
      "targetValueOne" (low bpm) / "targetValueTwo" (high bpm). Do NOT set "zoneNumber".
      This matches Garmin Connect's "Custom" heart rate target.
    For non-HR targets (pace, power, cadence), use targetValueOne/targetValueTwo directly.
    Pace targets are speeds in meters per second, not min/km:
    5:00/km = 1000 m / 300 s = 3.333 m/s.
    Target values are fields on the workout step, alongside targetType; do not put
    targetValueOne, targetValueTwo, or zoneNumber inside the targetType object.
    Use either zoneNumber or targetValueOne/targetValueTwo, not both. Garmin silently
    discards a custom range when a named zone is also present.

    Note: a safety check converts targetValueOne 1-5 to zoneNumber when zoneNumber is missing,
    to catch the common mistake of putting a zone index in targetValueOne. Typical bpm values
    (e.g. 105, 143) are not affected.

    IMPORTANT: Target type IDs and keys must match Garmin's canonical mapping.
    Garmin treats workoutTargetTypeId as authoritative, so mismatches are rejected
    before upload.  Known mappings:
    - workoutTargetTypeId 1  -> "no.target"
    - workoutTargetTypeId 2  -> "power.zone"  (cycling power zone 1-7, use zoneNumber)
    - workoutTargetTypeId 4  -> "heart.rate.zone"
    - workoutTargetTypeId 6  -> "pace.zone" (running/swim) OR "power.between" (cycling)

    IMPORTANT: For cycling power targets use the correct target type:
    - Power zone (zone 1-7 based on FTP %): use workoutTargetTypeId 2, key "power.zone",
      and "zoneNumber" (1-7).
    - Custom % FTP range (e.g. 76-81% FTP): use workoutTargetTypeId 2, key "power.zone",
      "targetValueOne"/"targetValueTwo" as percentages and
      "targetValueUnit": {"unitKey": "percent"}. Garmin Connect shows it as
      "Custom Power 76-81% FTP" with the matching watts.
    - Absolute watt range (e.g. 200-250 W): use workoutTargetTypeId 6, key "power.between",
      and "targetValueOne" (low watts) / "targetValueTwo" (high watts).
    Using workoutTargetTypeId 2 with key "power.between" is a silent Garmin bug: the
    workout uploads but Garmin stores it as "power.zone" and the intent is lost.

    Use {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"} with
    targetValueOne/targetValueTwo for custom heart-rate ranges.

    IMPORTANT: Sport type IDs for workouts (different from activity API!):
    - 1 = running, 2 = cycling, 5 = strength_training, 6 = cardio_training, 12 = walking

    IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping.
    Garmin treats conditionTypeId as authoritative, so mismatches such as
    {"conditionTypeId": 4, "conditionTypeKey": "heart.rate"} are rejected before
    upload because Garmin would interpret them as "calories". Use
    {"conditionTypeId": 6, "conditionTypeKey": "heart.rate"} for heart-rate
    end conditions.

    **Available Templates:**
    Instead of building workout JSON from scratch, you can use these MCP resources as starting points:
    - workout://templates/simple-run - Basic warmup/run/cooldown structure
    - workout://templates/interval-running - Interval training with repeat groups
    - workout://templates/tempo-run - Tempo run with heart rate zone targets
    - workout://templates/strength-circuit - Strength training with exercises, reps, rest
    - workout://reference/structure - Complete JSON structure reference with all fields

    Access these resources using your MCP client's resource reading capability, modify the template
    as needed, and pass the resulting JSON as the workout_data parameter.

    **Strength training workouts** require these additional fields on each exercise step:
    - "category": exercise category (e.g. "BENCH_PRESS", "PULL_UP", "CURL", "SHOULDER_PRESS",
      "ROW", "SQUAT", "DEADLIFT", "TRICEPS_EXTENSION", "PLANK", "LUNGE", "CARDIO")
    - "exerciseName": specific exercise (e.g. "BARBELL_BENCH_PRESS", "PULL_UP",
      "DUMBBELL_BICEPS_CURL", "DUMBBELL_SHOULDER_PRESS", "BENT_OVER_ROW_WITH_DUMBELL",
      "BODY_WEIGHT_DIP", "BARBELL_SQUAT", "BARBELL_DEADLIFT")
    - "weightValue" (optional): weight as number (e.g. 24.0)
    - "weightUnit" (optional): {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0}
    Use endCondition reps (conditionTypeId: 10) for exercises, rest (stepTypeId: 5) between sets.

    Example strength exercise step:
    {
        "type": "ExecutableStepDTO",
        "stepOrder": 1,
        "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
        "endCondition": {"conditionTypeId": 10, "conditionTypeKey": "reps"},
        "endConditionValue": 10.0,
        "targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"},
        "category": "BENCH_PRESS",
        "exerciseName": "BARBELL_BENCH_PRESS",
        "weightValue": 60.0,
        "weightUnit": {"unitId": 8, "unitKey": "kilogram", "factor": 1000.0}
    }

    Example running workout with HR zone target:
    {
        "workoutName": "My Workout",
        "sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
        "workoutSegments": [{
            "segmentOrder": 1,
            "sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
            "workoutSteps": [{
                "type": "ExecutableStepDTO",
                "stepOrder": 1,
                "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
                "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
                "endConditionValue": 1200.0,
                "targetType": {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"},
                "zoneNumber": 3
            }]
        }]
    }

    Args:
        workout_data: Dictionary containing workout structure (name, sport type, segments, etc.)
    

Inputs: workout_data (required).

upload_workoutsA

Upload multiple workouts from JSON data in a single call

    Creates multiple new workouts in Garmin Connect. Each item in the list
    uses the same structure as upload_workout.

    IMPORTANT: Step types must use Garmin's DTO format:
    - Use "ExecutableStepDTO" for regular steps (warmup, interval, cooldown, recovery)
    - Use "RepeatGroupDTO" for repeat/interval groups with numberOfIterations.
      Always include endCondition with conditionTypeId 7 and conditionTypeKey
      "iterations"; omitting conditionTypeId causes the API to silently corrupt
      the repeat count.
    - stepOrder is one depth-first counter over the whole workout: a repeat
      group takes the next number and its nested steps continue from there
      (group 2, children 3 and 4, cooldown 5). Do not restart at 1 inside a group.

    IMPORTANT: For named heart rate zone targets, use "zoneNumber" (1-5), NOT targetValueOne/targetValueTwo.
    For custom heart-rate ranges, use targetType {"workoutTargetTypeId": 4,
    "workoutTargetTypeKey": "heart.rate.zone"} with targetValueOne/targetValueTwo.
    Target values belong on the workout step, alongside targetType, not inside it.
    For cycling power zone targets (zone-based), use workoutTargetTypeId 2, key "power.zone".
    For cycling absolute watt range targets, use workoutTargetTypeId 6, key "power.between",
    with targetValueOne (low watts) and targetValueTwo (high watts).
    Pace targets use targetValueOne/targetValueTwo in meters per second, not
    min/km: 5:00/km = 1000 m / 300 s = 3.333 m/s.
    Target type IDs and keys must match Garmin's canonical mapping.

    IMPORTANT: End condition IDs and keys must match Garmin's canonical mapping.
    Garmin treats conditionTypeId as authoritative, so mismatches are rejected before upload.

    Args:
        workouts: List of workout dictionaries, each containing workout structure
                  (name, sport type, segments, etc.) — same format as upload_workout.
    

Inputs: workouts (required).

upsert_and_logA

Find-or-create a custom food then log it in one step

    Searches the user's custom food library for food_name. If found, logs
    it immediately. If not found, creates it with the provided nutrition
    data and then logs it. This avoids duplicate food entries and removes
    the need for separate search → create → log round-trips.

    Matching is by food_name alone (case-insensitive) — brand_name never
    affects find-or-create lookup, so it can't cause a duplicate by missing
    an existing unbranded record. If an existing match is found, it is
    logged as stored, using its first serving: calories, carbs, protein,
    fat, brand_name, serving_unit and number_of_units are all ignored and
    the stored food is not changed; only serving_qty applies. Those values
    only take effect when creating a new food. To change an existing
    food's nutrition, serving size or brand, use update_custom_food.

    On an error after creation, custom_food_created is true and
    write_committed describes the food log, not the library food. A failed
    or exhausted lookup never triggers another create automatically.

    Args:
        meal_date: Date in YYYY-MM-DD format
        meal_time: Time in HH:MM:SS format (account timezone); used to
            determine the meal automatically
        food_name: Name of the food to find or create
        calories: Calories per serving (new food only)
        carbs: Carbohydrates in grams per serving (new food only)
        protein: Protein in grams per serving (new food only)
        fat: Total fat in grams per serving (new food only)
        brand_name: Brand or vendor name (new food only)
        serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G"
            (new food only)
        number_of_units: Serving size in the specified unit. Default 100
            (new food only)
        serving_qty: Number of servings to log (default 1)
    

Inputs: calories (required), food_name (required), meal_date (required), meal_time (required), +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 157 tools

    Disambiguation3/5

    The set includes many near-duplicate pairs (e.g., get_sleep_summary vs get_sleep_data, get_stats vs get_user_summary vs get_stats_and_body, get_workouts vs get_scheduled_workouts vs get_garmin_coach_workouts), but most descriptions explicitly distinguish full-data vs summary and recommend one tool over another. However, with 157 tools, there are still multiple boundary cases an agent could easily misselect (e.g., the several workout-creation helpers, the two badge-challenge tools, and the get_activities variants).

    Naming Consistency4/5

    The dominant pattern is consistent snake_case verb_noun (get_*, set_*, add_*, delete_*, create_*, upload_*, download_*, schedule_*, unschedule_*). There are minor deviations such as get_userprofile_settings, get_activities_fordate, get_rhr_day, get_hrv_data, get_vo2max_trend, and the explicit get_training_plan_workouts alias, but these do not break readability.

    Tool Count1/5

    157 tools is far beyond a reasonable scoped surface, even for a broad health-and-fitness platform. Many domains (sleep, stress, activities, workouts, nutrition, devices, courses, gear, badges) are covered, but the sheer volume makes discovery and selection costly for an agent.

    Completeness4/5

    The surface is extremely comprehensive: CRUD for activities, workouts, nutrition, weight, courses, and many setters for activity metadata, plus extensive read coverage for devices, badges, goals, and trends. Minor gaps exist (e.g., no delete for body-composition/hydration/blood-pressure entries, no update-course, no gear creation), but agents can usually work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes Garmin Connect data through MCP, enabling retrieval of activities, health metrics, training status, and workouts, with OAuth authentication and confirmed write operations.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to read and update Garmin Connect data, including activities, health metrics, training status, and more, with per-account multi-tenant authentication.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an MCP client to read and write a personal Garmin Connect account: activities with per-set strength detail, daily health metrics (sleep, HRV, stress, steps, readiness), planned and completed workouts, and weigh-ins with body composition. It also logs finished strength sessions and body-composition readings as FIT files so they appear in Garmin Connect like natively recorded ones.
      38
      89 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives MCP clients read-only access to Garmin Connect data through Garmin's official Personal API, exposing daily metrics, sleep, activities, body composition, and related wellness endpoints via OAuth-protected remote tools.
      MIT