garmin-mcp
Provides tools to access Garmin Connect data, including sleep, activities, training load, HRV, body battery, steps, resting heart rate, and stress.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@garmin-mcp how did I sleep last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
garmin-mcp
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 |
| 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 |
| Sleep duration, stages (deep / light / REM / awake), score, overnight HRV. |
| List of recent activities with type, duration, distance, average heart rate. |
| Full metrics for one activity, including splits, HR zones, and power. |
| Daily training load with acute (ATL), chronic (CTL), ACWR, and current status. |
| Daily readiness score 0-100 with contributing factors (sleep, HRV, recovery). |
| Current HRV status, baseline range, and the last 7 nights of readings. |
| Body battery values across the day with min, max, charged, drained. |
| Daily step count, distance, calories, floors, and intensity minutes. |
| Resting heart rate trend and average over the requested window. |
| Stress levels across the day and time-in-zone breakdown. |
| Daily respiration rate: average, min, max, sleep vs waking. |
| VO2 max (running/cycling), fitness age, and predicted 5K/10K/half/marathon. |
| Personal records across activity types (fastest 1K/5K, longest run, etc.). |
| Weight, body fat, and muscle-mass trend over recent days. |
| Weekly aggregates for steps, stress, or intensity minutes. |
| Set-by-set breakdown of a strength session: exercises, reps, weight, volume. |
| Garmin endurance score with its per-activity-type contributors. |
| Garmin hill score (climbing strength + endurance) for a date. |
| 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 |
| Assembles a strength workout and shows the resolved Garmin exercises, per-exercise confidence, warnings, and a confirmation token. Makes no network call. |
| Creates the workout in your Garmin Connect library after you pass the confirmation token from |
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 loginPrompts 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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 |
|
macOS |
|
Windows |
|
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-mcpFor 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"andget_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_metricswalks back up to 7 days to surface your most recent reading rather than returning null on a rest day.get_stresszone-minute breakdown (rest_minutes,low_minutes, etc.) can come back null on partial-data days even thoughavg_stressand 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
garminconnectlibrary 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 (onlyupload_workoutis 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 testsAcknowledgements
garminconnectby cyberjunky for doing the hard work of reverse-engineering the Garmin Connect API.The Model Context Protocol team for the SDK.
Available Tools
28 toolscreate_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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides Claude with read-only access to Garmin Connect data including daily health metrics, training status, activity details, and trends through 32 tools.-
- AlicenseBqualityBmaintenanceEnables 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.63MIT
- AlicenseBqualityBmaintenanceEnables Claude and other MCP clients to query Garmin Connect health, training, activity, and body data, analyze FIT files, and create structured workouts that sync to a Garmin watch.39MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to read Garmin Connect data such as activities, sleep, HRV, VO2 max and training readiness, and optionally view or manage TrainingPeaks workouts and sync them to a watch, over streamable HTTP secured with MCP OAuth 2.1 and GitHub login.MIT