Skip to main content
Glama

garmin-mcp

PyPI Python License: MIT

An MCP server that exposes your Garmin Connect data to Claude as tools. Ask things like "how did I sleep last night?" or "summarise my training load this week" and Claude answers using your real Garmin data instead of you copy-pasting screenshots from the app.

Demo uses sample data. Regenerate with uv run --with pillow python scripts/make_demo_gif.py.

Single-user, and read-only by default — with one opt-in write path for creating strength workouts (see Write tools). Two ways to run it:

Mode

Where it runs

Works with

Setup

Local (stdio)

Your own machine

Claude Desktop

One command

Self-hosted HTTP

Cloud Run (or anywhere)

Claude.ai web, mobile, Desktop

~10 min, ~$0/mo

Tools

Tool

What it returns

get_daily_briefing

One-call morning snapshot — fuses sleep, HRV, Body Battery, readiness, training load, and resting HR (plus RHR vs. your baseline) so Claude can reason across them in a single shot. Each section degrades to null if unavailable.

get_sleep

Sleep duration, stages (deep / light / REM / awake), score, overnight HRV.

get_recent_activities

List of recent activities with type, duration, distance, average heart rate.

get_activity_details

Full metrics for one activity, including splits, HR zones, and power.

get_training_load

Daily training load with acute (ATL), chronic (CTL), ACWR, and current status.

get_training_readiness

Daily readiness score 0-100 with contributing factors (sleep, HRV, recovery).

get_hrv_status

Current HRV status, baseline range, and the last 7 nights of readings.

get_body_battery

Body battery values across the day with min, max, charged, drained.

get_steps_and_calories

Daily step count, distance, calories, floors, and intensity minutes.

get_resting_heart_rate

Resting heart rate trend and average over the requested window.

get_stress

Stress levels across the day and time-in-zone breakdown.

get_respiration

Daily respiration rate: average, min, max, sleep vs waking.

get_fitness_metrics

VO2 max (running/cycling), fitness age, and predicted 5K/10K/half/marathon.

get_personal_records

Personal records across activity types (fastest 1K/5K, longest run, etc.).

get_body_composition

Weight, body fat, and muscle-mass trend over recent days.

get_weekly_summary

Weekly aggregates for steps, stress, or intensity minutes.

get_strength_sets

Set-by-set breakdown of a strength session: exercises, reps, weight, volume.

get_endurance_score

Garmin endurance score with its per-activity-type contributors.

get_hill_score

Garmin hill score (climbing strength + endurance) for a date.

get_activity_weather

Weather recorded during an activity (temp, humidity, wind).

Every response is a Pydantic model serialised to JSON, with null for fields Garmin did not record.

Write tools (opt-in)

These create data in your Garmin account and are disabled unless you set GARMIN_WRITE_ENABLED=1. All other tools stay read-only regardless.

Tool

What it does

preview_strength_workout

Assembles a strength workout and shows the resolved Garmin exercises, per-exercise confidence, warnings, and a confirmation token. Makes no network call.

create_strength_workout

Creates the workout in your Garmin Connect library after you pass the confirmation token from preview_strength_workout.

Workflow: call preview_strength_workout, review the resolved exercises, then pass its confirmation_token to create_strength_workout (the token is bound to the exact workout previewed). The created workout lands in your Garmin Connect library — to get it on the watch, open it in Garmin Connect, tap Send to Device, then sync. Free-text exercise names are matched against Garmin's catalog (data/exercise_taxonomy.json); names that don't map cleanly are flagged in the preview. Deleting and scheduling are intentionally not exposed.

Related MCP server: garmin-mcp

Quick start — Claude Desktop

Requires Python 3.12+ and uv (install with curl -LsSf https://astral.sh/uv/install.sh | sh).

1. Authorise once

uvx garmin-mcp login

Prompts for your Garmin email, password, and MFA code (if enabled), then saves session tokens to your user cache directory. You won't be prompted again until the tokens eventually expire (typically weeks to months).

2. Add the server to Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop. The Garmin tools appear in the tool picker. Ask Claude "what was my resting heart rate this week?" to test.

3. (Optional) Set credentials for unattended re-auth

By default, when Garmin tokens expire you'll see a "saved Garmin session is invalid" error and you'll need to re-run uvx garmin-mcp login. To skip that step, put your credentials in the config so the server can silently re-authenticate:

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-mcp"],
      "env": {
        "GARMIN_EMAIL": "you@example.com",
        "GARMIN_PASSWORD": "your-garmin-password"
      }
    }
  }
}

Anyone with read access to this file can see these credentials.

Where session tokens are stored

garmin-mcp login writes session tokens to your platform's user cache directory:

OS

Path

Linux

~/.cache/garmin-mcp/garth/

macOS

~/Library/Caches/garmin-mcp/garth/

Windows

%LOCALAPPDATA%\garmin-mcp\Cache\garth\

Delete the garth/ directory to "log out" of Garmin.

Self-hosted HTTP (Claude.ai web/mobile)

If you want the connector available from Claude.ai on the web or your phone, run the same server in HTTP mode. The serve subcommand wraps it in an OAuth 2.1 layer with PKCE and Dynamic Client Registration so Claude.ai can connect to it as a custom connector.

See DEPLOY.md for the Cloud Run walkthrough. The short version:

docker build -t garmin-mcp .
docker run --rm -p 8080:8080 \
  -e MCP_ISSUER_URL=http://localhost:8080 \
  -e MCP_AUTH_PASSWORD=$(openssl rand -base64 24) \
  -e JWT_SECRET=$(openssl rand -base64 48) \
  -e GARMIN_EMAIL=you@example.com \
  -e GARMIN_PASSWORD=your-garmin-password \
  garmin-mcp

For Cloud Run, the always-free tier covers personal usage. Expect under $1/month.

How auth works (HTTP mode)

The server is its own OAuth 2.1 authorisation server. When you add the connector in Claude.ai, Claude registers itself using RFC 7591 Dynamic Client Registration, then sends you through a PKCE-protected flow. You enter the password set as MCP_AUTH_PASSWORD, and the server issues a 24-hour JWT access token plus a refresh token that rotates on every use.

This is intentionally minimal: one password, one user. Anyone with the password can read your Garmin data.

Data availability

Garmin returns sparse data depending on which watch you wear, how long you've worn it, and what features your model supports. Every tool follows the same convention: when a field isn't recorded, the response carries null for that field (and often a note explaining the absence) rather than erroring.

A few specific cases worth knowing about:

  • get_training_load.current_status = "NO_STATUS_2" and get_hrv_status.status = "NONE" mean Garmin doesn't have enough recent activity history to compute the metric. They fill in naturally after ~7 consecutive days of sustained activity or watch wear.

  • VO2 max only updates after qualifying activities (runs, rides). get_fitness_metrics walks back up to 7 days to surface your most recent reading rather than returning null on a rest day.

  • get_stress zone-minute breakdown (rest_minutes, low_minutes, etc.) can come back null on partial-data days even though avg_stress and the timeline are populated.

  • HRV, training readiness, endurance score, hill score, and fitness age all require a recent compatible watch (Fenix 6+ / Forerunner 245+ / similar). Older watches simply won't report them.

If a tool seems to return less than you'd expect, check the same metric in the Garmin Connect app or on connect.garmin.com for the same date. If Garmin shows it there and we return null, that's a parser bug — file an issue with the date and the field name and we can usually map it in a follow-up release.

Security caveats

  • This is single-user software. Don't run it as a shared service for multiple Garmin accounts — you'd be holding other people's credentials, and it likely violates Garmin's ToS.

  • Garmin credentials and session tokens live on your local machine. Treat any password you put in a JSON config file as compromised in the long term — use a dedicated Garmin account if that's a concern.

  • The unofficial garminconnect library can break when Garmin changes their internal API. If a tool starts returning empty data, check that package's changelog.

  • In HTTP mode, registered DCR clients and refresh tokens live in process memory and disappear on restart. Access tokens (JWTs) survive because they are stateless.

  • Read-only by default. The one write path — creating strength workouts — is off unless you set GARMIN_WRITE_ENABLED=1, and is enforced at the client layer by a method allowlist (only upload_workout is writable; no activity upload, profile edits, deletes, or scheduling). Each create requires a preview→token confirmation, and in HTTP mode the server refuses to start with writes enabled but auth disabled.

Project layout

garmin-mcp/
├── pyproject.toml
├── Dockerfile
├── README.md
├── DEPLOY.md
└── src/
    └── garmin_mcp/
        ├── __init__.py
        ├── __main__.py        # python -m garmin_mcp -> CLI
        ├── cli.py             # argparse entry: stdio / serve / login
        ├── server.py             # FastMCP app, tools, login UI
        ├── garmin_client.py      # garminconnect wrapper (read allowlist + write gate)
        ├── auth.py               # OAuth 2.1 provider
        ├── cache.py              # TTL cache
        ├── paths.py              # token directory resolution
        ├── exercise_resolver.py  # free-text exercise -> Garmin (category, name)
        ├── strength_builder.py   # strength workout spec -> Garmin payload
        ├── models.py             # Pydantic response models
        └── data/
            └── exercise_taxonomy.json   # Garmin's exercise catalog (resolver data)

Contributing

git clone https://github.com/Tyler-Irving/garmin-mcp.git
cd garmin-mcp
uv sync --extra dev

uv run garmin-mcp login                       # one-time interactive login
uv run mcp dev src/garmin_mcp/server.py       # inspect tools in MCP Inspector
uv run garmin-mcp                             # stdio mode
uv run garmin-mcp serve                       # HTTP mode

uv run pytest                                 # tests
uv run ruff check . && uv run ruff format --check .
uv run mypy src tests

Acknowledgements

Available Tools

28 tools
create_running_workoutA

Create a structured running workout in your Garmin Connect library (a WRITE).

Supports warmup/cooldown/interval/recovery steps, repeat groups for intervals, and optional pace targets ('M:SS' per km). Requires writes to be enabled (GARMIN_WRITE_ENABLED) and a matching confirmation_token from preview_running_workout. The workout lands in your library — get it on the watch via schedule_workout (syncs automatically for that date) or "Send to Device" in Garmin Connect.

Args: workout: the workout definition (same shape as preview). confirmation_token: token returned by preview_running_workout. confirm: dev/stdio only (no JWT secret) — set True to confirm.

Inputs: workout (required), confirm, confirmation_token. Returns: name, status, workout_id

create_strength_workoutA

Create a strength workout in your Garmin Connect library (a WRITE).

Requires writes to be enabled (GARMIN_WRITE_ENABLED) and a matching confirmation_token from preview_strength_workout (it binds to the exact workout previewed). The workout lands in your library — it reaches the watch only after you "Send to Device" in Garmin Connect and sync.

Args: workout: the workout definition (same shape as preview). confirmation_token: token returned by preview_strength_workout. confirm: dev/stdio only (no JWT secret) — set True to confirm.

Inputs: workout (required), confirm, confirmation_token. Returns: name, status, verified, workout_id, +1 more

delete_workoutA

Delete ONE workout from your Garmin Connect library (a WRITE, irreversible).

Preview-then-confirm: call without a token first — that call deletes nothing and returns the workout's name plus a confirmation_token. Review the name, then call again with the token to actually delete. Deleting from the library also removes the workout from the watch on its next sync. There is no bulk delete; confirm each workout individually.

Args: workout_id: id from list_workouts. confirmation_token: token from the preview call for this same id. confirm: dev/stdio only (no JWT secret) — set True to confirm.

Inputs: workout_id (required), confirm, confirmation_token. Returns: name, status, deleted, workout_id, +1 more

get_activity_detailsA

Detailed metrics for one activity, including splits and HR zones.

Args: activity_id: The activity's numeric Garmin ID, as returned by get_recent_activities.

Inputs: activity_id (required). Returns: name, splits, calories, hr_zones, +16 more

get_activity_weatherA

Weather conditions recorded during an activity (temp, humidity, wind).

Units follow your Garmin account's measurement system (US accounts report degrees Fahrenheit and mph).

Args: activity_id: The activity's numeric Garmin ID, from get_recent_activities.

Inputs: activity_id (required). Returns: Weather observed during an activity. Units follow your Garmin account's measure…

get_body_batteryA

Body battery values across the day, plus min, max, charged, and drained totals.

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

Inputs: date. Returns: date, charged, drained, timeline, +3 more

get_body_compositionA

Weight, body fat, and muscle-mass trend over recent days.

Returns one row per day Garmin has a reading for, plus the latest weight and average over the window.

Args: end_date: End of the window in YYYY-MM-DD format. Defaults to today. days: Window size in days. Capped at 90.

Inputs: days, end_date. Returns: days, note, avg_weight_kg, latest_weight_kg

get_daily_briefingA

One-call morning snapshot: sleep, HRV, Body Battery, readiness, load, and RHR.

Fuses the individual recovery and training-load tools into a single payload so you can reason across them in one shot instead of making six separate calls. Each section is fetched independently and concurrently; a section that fails comes back null and is named in sections_unavailable rather than failing the whole briefing. Also returns rhr_vs_baseline_bpm, the most recent resting HR relative to its trailing average.

The server returns facts only and computes no training advice — interpret the numbers yourself (e.g. weigh readiness, HRV status, and Body Battery together).

Args: date: Calendar date in YYYY-MM-DD format. Defaults to today. The sleep, Body Battery, and training-readiness sections honour this date; the HRV, training-load, and resting-HR sections always report their own most-recent trailing window. For the default (this-morning) call everything lines up; passing a past date yields a mixed snapshot.

Inputs: date. Returns: A one-call morning snapshot fusing the key recovery and load signals. Each sect…

get_endurance_scoreA

Garmin endurance score with its activity-type contributors.

The endurance score reflects accumulated aerobic capacity across activities. It only updates after qualifying activities, so a given day may have no value.

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

Inputs: date. Returns: date, note, contributors, overall_score, +4 more

get_fitness_metricsA

VO2 max (running and cycling), fitness age, and predicted race times.

Combines Garmin's "max metrics" tile (VO2 max, fitness age) with current race-time predictions for 5K, 10K, half marathon, and marathon.

Args: date: Calendar date for the VO2 max snapshot in YYYY-MM-DD format. Defaults to today.

Inputs: date. Returns: date, note, fitness_age, vo2_max_cycling, +2 more

get_hill_scoreA

Garmin hill score (climbing strength + endurance) for a date.

Combines a strength and an endurance component into an overall hill score. Requires qualifying climbing efforts, so it is often empty for flat-terrain athletes — an empty result is reported via note rather than an error.

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

Inputs: date. Returns: date, note, vo2_max, overall_score, +4 more

get_hrv_statusA

Current HRV status, baseline range, and the last 7 nights of readings.

Inputs: no named parameters. Returns: status, feedback, last_7_days, weekly_avg_ms, +3 more

get_personal_recordsA

Personal records across activity types (fastest 1K/5K/10K, longest run, etc.).

Inputs: no named parameters. Returns: count, records

get_recent_activitiesA

List recent activities with type, duration, distance, and average heart rate.

Args: limit: How many of the most recent activities to return. Capped at 50.

Inputs: limit. Returns: count, activities

get_respirationA

Daily respiration rate: average, min, max, and waking vs. sleeping averages.

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

Inputs: date. Returns: date, note, avg_breaths_per_min, lowest_breaths_per_min, +3 more

get_resting_heart_rateA

Resting heart rate trend over the last days days.

Args: days: How many recent days to include. Capped at 28.

Inputs: days. Returns: days, avg_rhr_bpm

get_sleepA

Sleep duration, sleep stages, sleep score, and overnight HRV.

Args: date: Calendar date in YYYY-MM-DD format. Defaults to last night (yesterday). Pass today's date to get the most recent recorded sleep when you wake up.

Inputs: date. Returns: One night of sleep, summarised.

get_steps_and_caloriesA

Daily step total, distance, calories, floors, and intensity minutes.

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

Inputs: date. Returns: date, step_goal, total_steps, bmr_calories, +6 more

get_strength_setsA

Set-by-set breakdown of a logged strength session: exercises, reps, and weight.

Parses Garmin's recorded sets for one strength_training activity into working sets (with the recognised exercise, rep count, and load) plus a per-exercise rollup and total training volume. Rest periods are included and flagged. Sets Garmin could not classify come back with a null exercise name.

Args: activity_id: The activity's numeric Garmin ID, from get_recent_activities.

Inputs: activity_id (required). Returns: Set-by-set breakdown of a logged strength_training activity.

get_stressB

Stress levels across the day with average, max, and time-in-zone breakdown.

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

Inputs: date. Returns: date, timeline, avg_stress, max_stress, +4 more

get_training_loadB

Daily training load with acute and chronic load and current status.

Args: days: Number of recent days to summarise. Capped at 28.

Inputs: days. Returns: days, acwr_status, current_atl, current_ctl, +2 more

get_training_readinessA

Daily training readiness score (0-100) with contributing factors.

The score reflects how prepared the user is to train, drawing on sleep, HRV status, recovery time, and recent training load.

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

Inputs: date. Returns: date, note, level, score, +9 more

get_weekly_summaryA

Weekly aggregates for a single metric.

Args: metric: One of "steps", "stress", or "intensity_minutes". weeks: How many recent weeks to include. Capped at 12. end_date: End of the window in YYYY-MM-DD format. Defaults to today.

Inputs: metric (required), weeks, end_date. Returns: note, weeks, metric, avg_value

list_workoutsA

List workouts saved in your Garmin Connect library (id, name, sport).

These are workout templates in the library — the source the watch syncs from — not logged activities. Use the ids with delete_workout.

Args: limit: maximum number of workouts to return (default 50).

Inputs: limit. Returns: count, workouts

preview_running_workoutA

Assemble a running workout and show what WOULD be created — no network call.

Validates the structure (one end condition per step, paired pace bounds, pace format) and returns a readable summary, sanity warnings, and a confirmation_token to pass to create_running_workout. Always call this first and review the result.

Args: workout: the workout definition (name, steps and/or repeat groups).

Inputs: workout (required). Returns: name, summary, warnings, confirmation_token, +1 more

preview_strength_workoutA

Assemble a strength workout and show what WOULD be created — no network call.

Resolves each exercise name to Garmin's catalog and returns a readable summary, the resolved Garmin name + confidence per exercise, warnings for anything that did not map cleanly, and a confirmation_token to pass to create_strength_workout. Always call this first and review the result.

Args: workout: the workout definition (name, blocks of sets/exercises).

Inputs: workout (required). Returns: name, summary, warnings, exercises, +1 more

schedule_workoutA

Put an existing library workout on a Garmin Connect calendar date (a WRITE).

Works for any workout type (running, strength, ...). A scheduled workout is pushed to the watch automatically on its next sync — no "Send to Device" needed. Reversible with unschedule_workout.

Args: workout_id: id from create_running_workout / create_strength_workout / list of workouts in Garmin Connect. date: calendar date, YYYY-MM-DD.

Inputs: date (required), workout_id (required). Returns: status, workout_id, schedule_id, workout_name, +1 more

unschedule_workoutA

Remove a scheduled workout from the calendar (a WRITE; keeps the template).

The workout stays in your library — only the calendar entry is removed.

Args: schedule_id: id returned by schedule_workout.

Inputs: schedule_id (required). Returns: status, schedule_id

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most get_* tools target distinct metrics (sleep, HRV, body battery, stress, etc.), but some overlap exists: get_sleep includes overnight HRV, and get_daily_briefing explicitly fuses six other tools. Descriptions are detailed enough to disambiguate, but an agent could hesitate between the composite and individual tools.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case: get_* for read operations, preview_*/create_* for workout creation, delete_workout, schedule_workout/unschedule_workout. Nearly every tool name clearly indicates its action and resource, with no mixed conventions.

    Tool Count2/5

    With 28 tools, the server exceeds the 25+ threshold for 'too many'. While the Garmin domain is broad, many tools could be consolidated (e.g., get_daily_briefing already combines six), and the count feels heavy for an agent to navigate efficiently.

    Completeness4/5

    The surface covers a wide range of health metrics and workout CRUD (preview, create, list, delete, schedule/unschedule). Minor gaps exist: no workout update (only delete and recreate) and no detailed view of a single workout template's steps, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables Claude to access and query your Garmin Connect data—sleep, training, heart rate, and more—through a suite of read-only tools, with an optional write path for creating strength workouts.
      63
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables users to query their own Garmin Connect data—such as recovery, sleep, HRV, activities, and daily wellness—through a read-only remote MCP connection secured with OAuth, including from the Claude mobile app.
      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