Skip to main content
Glama
Garmin Health MCP

Garmin Health MCP

by EmilbMadsen

garmin-health-mcp

Unofficial, read-only MCP server for the Garmin Connect Personal API.

Unofficial, not affiliated with Garmin. Single-user and self-hosted only: a Personal API key may only be used by its owner. Do not run this as a shared or hosted service.

CI PyPI

Lets Claude (or any MCP client) read your own sleep, HRV, heart rate, stress, Body Battery, weight, nutrition and activities, including laps, splits and time in heart-rate zones from the original FIT files. It uses Garmin's official, key-based Personal API, so there is no password login and no scraping. See docs/capabilities.md for what each endpoint returns.

Requirements

Related MCP server: garmin-personal-mcp

Setup

Store the key in the system keyring (macOS Keychain, Windows Credential Locker or the Secret Service on Linux). setup verifies it with one call before saving it:

uvx garmin-health-mcp setup

uvx garmin-health-mcp setup --delete removes it again. The key is looked up in this order: GARMIN_PERSONAL_API_KEY_FILE, then GARMIN_PERSONAL_API_KEY, then the keyring (service garmin-health-mcp). It is never printed, logged or written to .env. Garmin's bearer token is cached with mode 0600 in GARMIN_HEALTH_MCP_STATE_DIR (default ~/.config/garmin-health-mcp/, mode 0700).

Use with Claude

The server runs over stdio: your MCP client starts it when needed.

Claude Code:

claude mcp add --scope user garmin-health -- uvx garmin-health-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS), then restart Claude Desktop:

{
  "mcpServers": {
    "garmin-health": {
      "command": "uvx",
      "args": ["garmin-health-mcp"]
    }
  }
}

If Claude Desktop cannot find uvx, use its full path (which uvx). The server is named garmin-health, so it can run next to another Garmin MCP server without tool name clashes.

Remote access (claude.ai and the Claude mobile app)

garmin-health-mcp serve --http serves Streamable HTTP at /mcp, protected by a built-in single-user OAuth 2.1 server: one static client (no dynamic registration), PKCE S256, login with password + TOTP, 1-hour access tokens, rotating 30-day refresh tokens with reuse detection, and garmin-health-mcp auth revoke-all as an emergency brake. Without --http it runs stdio with no auth, as before.

Tools

All tools are read-only. Dates are YYYY-MM-DD; single-day tools default to today and range tools to the last 7 days (at most 1 year).

Tool

Data

get_sleep

one night in detail: stages, sleep score and factors, HR, SpO2, respiration, sleep need

get_sleep_summaries

compact sleep summary per night over a range

get_hrv / get_hrv_summaries

HRV status, last-night average, baseline (optional 5-min readings)

get_body_battery

charged/drained, level over the day, events with impact

get_stress

daily stress level and time per stress band

get_steps

daily steps, distance, goal

get_daily_summaries

one overview per day: movement, calories, HR, intensity minutes, stress, Body Battery, respiration, pulse ox

get_heart_rate

resting HR, 7-day average, min/max, hourly min/avg/max (optional raw samples)

get_heart_rate_zones

zone floors per sport and the HR values used

get_spo2

SpO2 averages and hourly averages

get_fitness_age

fitness age and its components

get_weight / get_weight_goals

weigh-ins and goals

get_hydration / get_food_logs

logged water and food

get_wellness_activity_summaries

wellness activities

get_profile_settings

units, locale, time zone (no name or other personal data)

search_activities

activities with training effect, training load and time in HR zones

get_activity / get_activity_workouts

one activity in detail and its planned workout

get_activity_laps

laps from the FIT file: pace, GAP, HR, cadence, power, ascent, intensity

get_activity_splits

even splits (per km or any distance) computed from the recorded data

get_activity_time_in_hr_zones

time in zones from recorded HR, with current or recorded zones

get_activity_summary_stats

session stats incl. running dynamics, power, respiration, RPE

Menstrual-cycle data is off by default; set GARMIN_HEALTH_MCP_ENABLE_CYCLE=1 to add get_menstrual_cycle.

Not available through the Personal API: training readiness, training status, race predictions, VO2 max, calendar and workouts. See docs/capabilities.md.

FIT-file analysis

The four get_activity_* analysis tools download the activity's original FIT file once and cache it in <state dir>/fit/<activity_id>.fit (directory 0700, files 0600; it is health data). It is decoded with Garmin's FIT SDK. Splits and zone times exclude paused time; elevation uses a 1.5 m hysteresis against barometer noise; running cadence is reported in steps/min. Raw record streams and GPS positions are never returned. Delete the cache directory at any time to free space.

What the server does to responses

  • Time: every GMT timestamp (epoch ms or naive string) becomes ISO 8601 in GARMIN_HEALTH_MCP_TZ (default Europe/Copenhagen). The GMT suffix is dropped from the key and the duplicate ...Local field is removed.

  • Noise and privacy: null and empty fields, names, display names, profile/owner/device IDs, profile image URLs and GPS start/end coordinates are removed.

  • Size: long series (heart rate, SpO2, HRV readings) are summarized; raw samples are opt-in.

  • Reliability: HTTP 401 triggers one token refresh; 429/5xx and network errors are retried with exponential backoff and jitter (3 attempts, Retry-After honoured); date ranges are split into chunks the API accepts.

  • Logs: method, path and status only. Response bodies are health data and are never logged.

Contributing

See CONTRIBUTING.md. Test fixtures are synthetic: scripts/anonymize.py keeps the structure of real responses but replaces every identifier and value.

Disclaimer

Unofficial project, not affiliated with or endorsed by Garmin. Garmin Connect is a trademark of Garmin Ltd. Use your own Personal API key for your own data only, within Garmin's terms. This is not medical software.

Credits

License

Apache-2.0, see LICENSE.

Available Tools

25 tools
get_activityA
Read-only

Details of one activity: summary (distance, durations, speed, heart rate, calories, training effect and load, intensity minutes, steps), type, time zone and device.

Inputs: activity_id (required). Returns: object

get_activity_lapsA
Read-only

Laps of one activity from its FIT file: distance, timer time, pace (or speed), grade- adjusted pace, average/max heart rate, cadence, power, ascent/descent, intensity (active, rest, warmup, cooldown) and what ended the lap (manual, distance, time). For structured workouts and intervals, laps are the reps.

Inputs: activity_id (required). Returns: object

get_activity_splitsA
Read-only

Even distance splits of one activity (per km by default), computed from the recorded data: time, pace, average/max heart rate, cadence, power and elevation gain/loss per split. Paused time is excluded. The last split is usually shorter. Needs distance data.

Inputs: activity_id (required), split_meters. Returns: object

get_activity_summary_statsB
Read-only

Session summary from the activity's FIT file: distance, timer and elapsed time, pace and best pace (or speed), grade-adjusted pace, heart rate, cadence, power (avg, max, normalized), ascent/descent, calories, aerobic and anaerobic training effect, training load, running dynamics (ground contact time and balance, vertical oscillation and ratio, step length), respiration rate, perceived effort and feel, and which data the file contains.

Inputs: activity_id (required). Returns: object

get_activity_time_in_hr_zonesA
Read-only

Time in heart rate zones for one activity, computed from the recorded heart rate: seconds and percent below zone 1 and in zones 1-5, with each zone's bpm range. Paused time is excluded. Also returns the watch's own time-in-zone totals for comparison.

Inputs: activity_id (required), zones. Returns: object

get_activity_workoutsB
Read-only

The planned workout (steps and targets) the activity was recorded against, if any.

Inputs: activity_id (required). Returns: object

get_body_batteryB
Read-only

Body Battery per day: charged and drained, level over the day, and events that changed it (sleep, activities, stress) with their impact and Garmin's feedback.

Inputs: end_date, start_date. Returns: object

get_daily_summariesA
Read-only

One overview per day: steps and floors, calories (active, resting, total), heart rate (min, max, resting), intensity minutes vs goal, stress breakdown, Body Battery (min, max, charged, drained), hydration, respiration and pulse ox. The best single call for "how was my day/week". Durations are in milliseconds.

Inputs: end_date, start_date. Returns: object

get_fitness_ageB
Read-only

Garmin fitness age vs chronological age, and its components (vigorous days and minutes, resting heart rate, BMI).

Inputs: date. Returns: object

get_food_logsA
Read-only

Foods logged in Garmin Connect for one day, with meals and serving sizes. Empty if the user does not log food in Garmin.

Inputs: date. Returns: object

get_heart_rateA
Read-only

Heart rate for one day: resting heart rate, 7-day average resting heart rate, min and max, and min/avg/max per hour.

Inputs: date, include_samples. Returns: object

get_heart_rate_zonesA
Read-only

The user's heart rate zones per sport: zone floors 1-5, method (e.g. % of max HR or HR reserve), and the max, resting and lactate threshold heart rate used.

Inputs: no named parameters. Returns: object

get_hrvA
Read-only

Heart rate variability for one night: last-night average, 5-minute high, weekly average, personal baseline band and HRV status (e.g. BALANCED, UNBALANCED, LOW).

Inputs: date, include_readings. Returns: object

get_hrv_summariesA
Read-only

HRV summary per night over a date range: last-night average, weekly average, baseline band and status. Best for HRV trends.

Inputs: end_date, start_date. Returns: object

get_hydrationB
Read-only

Logged water intake per day. Empty if the user does not log hydration.

Inputs: end_date, start_date. Returns: object

get_profile_settingsC
Read-only

The user's unit system, locale, time zone, first day of week and date/time formats.

Inputs: no named parameters. Returns: object

get_sleepA
Read-only

Full sleep record for one night (the date the user woke up): sleep and wake time, time in deep/light/REM/awake, sleep score with per-factor ratings and optimal ranges, average heart rate, SpO2, respiration, sleep stress, awake count, and sleep need for today and tomorrow.

Inputs: date. Returns: object

get_sleep_summariesA
Read-only

Compact sleep summary per night over a date range: duration, stages, sleep score, average heart rate, stress, SpO2 and respiration. Use get_sleep for one night in detail.

Inputs: end_date, start_date. Returns: object

get_spo2B
Read-only

Blood oxygen (SpO2) for one day: day and sleep averages, lowest, latest, 7-day average, and hourly averages.

Inputs: date. Returns: object

get_stepsB
Read-only

Daily steps, distance (meters) and step goal.

Inputs: end_date, start_date. Returns: object

get_stressB
Read-only

Daily stress: overall stress level (0-100) and seconds spent at rest and in low, medium and high stress.

Inputs: end_date, start_date. Returns: object

get_weightB
Read-only

Weigh-ins in a date range (weight in grams, BMI and body composition if measured), the range average, and the nearest weigh-in before and after the range.

Inputs: end_date, start_date. Returns: object

get_weight_goalsC
Read-only

Weight goals in effect during a date range.

Inputs: end_date, start_date. Returns: object

get_wellness_activity_summariesC
Read-only

Wellness activity summaries (e.g. breathwork or relaxation sessions) in a date range.

Inputs: end_date, start_date. Returns: object

search_activitiesC
Read-only

Recorded activities, newest first: name, type, start time, distance (m), duration (s), speed (m/s), calories, average/max HR, aerobic and anaerobic training effect, training load, seconds in HR zones 1-5, intensity minutes, Body Battery change and strength sets.

Inputs: limit, start, end_date, start_date, +1 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target clearly distinct Garmin data domains, and the descriptions explicitly differentiate summary vs. detail tools such as get_sleep/get_sleep_summaries and get_hrv/get_hrv_summaries. There is still some overlap because get_daily_summaries aggregates many of the same metrics exposed by get_steps, get_heart_rate, get_stress, get_body_battery, get_spo2, and get_hydration.

    Naming Consistency5/5

    Names are consistently snake_case and almost all use the get_<resource> pattern, with activity sub-resources predictably namespaced under get_activity_*. The single search_activities tool uses a different verb but still follows the same verb_noun convention and is semantically clear.

    Tool Count3/5

    At 25 tools this is at the heavy end of the scale, and several tools are close summary/detail pairs or activity sub-metric calls that could be consolidated. Each tool covers a real data slice, but the surface feels broad and somewhat fragmented for an agent to navigate.

    Completeness4/5

    The read-only surface is broad, covering daily wellness, sleep, HRV, body battery, stress, weight, hydration, food, and detailed activity analysis. Minor gaps remain, such as training status/readiness, VO2 max, personal records, and planned-workout listing, but core health workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to access and query your Garmin Connect data, including sleep, activities, training load, and health metrics, through a set of read-only MCP tools.
      28
      199 PyPI
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Garmin Connect for Claude and any MCP client, on Garmin's official Personal API. Read-only access to sleep, HRV, Body Battery, stress, heart rate, activities and weight with a revocable key, no password or scraping.
      26
      1,568 PyPI
      69
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude and any MCP client to read a user's own Garmin account in plain language, covering activities, time-series charts, thresholds, sleep, HRV, Body Battery, stress, readiness and trends. It also serves a private local dashboard that downloads the full training and health history, correlates metrics across views, and exports any table as CSV.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude to read and review your own Garmin training and recovery data through Garmin's official Connect Personal API, with tools for activities, daily summaries, sleep, HRV, and period analytics.
      7
      1
      MIT