garmin-coach
Provides read access to Garmin Connect health and training data, including daily health metrics, sleep, HRV, stress, heart rate, workouts, activities, and exercise history. With writes enabled, it can also create, schedule, and push workouts to Garmin devices.
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-coach How did I sleep and what's my training readiness today?"
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-coach
A local stdio MCP server that gives Claude Code read access to your Garmin Connect account, plus a gated, allow-listed path for creating and scheduling workouts. Intended as the data layer for an AI training/fat-loss coach.
Architecture
Claude Code
↓ MCP (stdio, local subprocess — no network)
garmin_mcp.server 25 read-only tools (+6 when writes are enabled)
↓
garmin_mcp.client token-only auth, error normalisation
↓ python-garminconnect 0.3.11
Garmin Connect (HTTPS)
↓ device sync
Garmin Forerunner 970Everything runs on your Mac. The only network traffic is normal HTTPS to Garmin. Nothing is sent to a third party.
Related MCP server: garmin-mcp
Install
cd ~/Developer/garmin-coach
uv syncPython is pinned to 3.12 via .python-version. garminconnect requires ≥3.12.
Initial Garmin login — run this yourself
Credentials are only ever entered interactively, in your own terminal:
cd ~/Developer/garmin-coach
uv run python scripts/garmin_login.pyIt prompts for your email, then your password via getpass (hidden, never in
shell history), and handles an MFA code if Garmin asks. On success it mints
OAuth tokens and does a small harmless read to prove the session works.
If Garmin starts rate limiting, the script stops and tells you to wait — it does not retry in a loop, which is what gets accounts throttled harder.
Token storage and security
Tokens live in
~/.garmin-coach/tokens— outside the project, so they can never be swept into git.The directory is forced to
0700, every file inside to0600.Your password is used exactly once, to mint tokens. It is never stored, never written to
.env, never in MCP config, never in the repo.Token contents are never logged. Logging goes to stderr only (stdout is the MCP protocol channel).
Override the location with
GARMIN_TOKENSTORE=/some/path.
Treat ~/.garmin-coach/tokens as equivalent to your password. Anyone with
those files has full read/write access to your Garmin account.
Test the MCP
uv run python scripts/smoke_test.pyStage 1 runs without any Garmin auth — it exercises the stdio transport, tool discovery, the bundled exercise catalog, the workout builder, and the error paths. Stage 2 runs the live read tools, and is skipped automatically until you have logged in.
Connect to Claude Code
Already registered user-scoped (available in every project):
claude mcp add --scope user garmin -- \
/opt/homebrew/bin/uv run --directory ~/Developer/garmin-coach \
python -m garmin_mcp.server
claude mcp get garmin # check statusuv run --directory resolves the project's own virtualenv, so you never need
to activate anything manually.
Tools
Health — garmin_today, garmin_sleep, garmin_hrv, garmin_stress,
garmin_body_battery, garmin_heart_rate, garmin_recovery
Training — garmin_training_readiness, garmin_training_status,
garmin_hr_zones, garmin_performance_metrics, garmin_recent_activities,
garmin_activities_by_date, garmin_activity, garmin_strength_sets,
garmin_exercise_history
Workout library (read-only) — garmin_workouts, garmin_workout,
garmin_scheduled_workouts, garmin_search_exercises,
garmin_exercise_categories, garmin_resolve_exercise,
garmin_workout_step_formats, garmin_devices,
garmin_preview_strength_workout
All dates are ISO YYYY-MM-DD and default to today. Responses are normalised
and compact; a value Garmin did not return is omitted rather than guessed,
so "field absent" and "value is zero" stay distinguishable.
Write tools (disabled by default)
Not registered at all unless GARMIN_MCP_ENABLE_WRITES=1 is in the server
environment, and independently re-checked at call time:
garmin_create_strength_workout, garmin_create_cardio_workout,
garmin_update_workout, garmin_schedule_workout,
garmin_unschedule_workout, garmin_push_workout_to_device
This is an allow-list, not a passthrough. Deleting activities, gear, or
profile data is not exposed. garmin_unschedule_workout additionally requires
confirm=true.
To enable:
claude mcp remove garmin -s user
claude mcp add --scope user garmin -e GARMIN_MCP_ENABLE_WRITES=1 -- \
/opt/homebrew/bin/uv run --directory ~/Developer/garmin-coach \
python -m garmin_mcp.serverUse garmin_preview_strength_workout first — it builds and renders the exact
payload without uploading. Verify the structure before anything reaches your
calendar or watch.
Known Garmin limitations
The unofficial API does not expose everything the watch shows. The full
matrix — what's on the watch vs in Garmin Connect vs reachable via
python-garminconnect — is in docs/forerunner-970.md.
The ones that shape the coaching design:
No RIR/RPE field exists. Garmin has nowhere to put it.
Garmin stores one concrete rep target per set, not a range. A "5–8 @ 1 RIR" prescription cannot round-trip — push the concrete target (e.g. 6) and keep the programming rule in the coaching layer. Garmin is the execution interface, not the source of truth for the program.
Per-set heart rate is not available; HR is session-level only.
Auto-detected reps are often wrong for machines/cables until corrected in Garmin Connect.
Use
garmin_hr_zones, never computed zones. Zone 2 is a heart-rate range from your Garmin profile, not a hard-coded pace.
Re-authenticate or revoke
rm -rf ~/.garmin-coach/tokens # revoke locally
uv run python scripts/garmin_login.py # re-authenticateTokens auto-refresh, so this is only needed if the refresh token expires or you revoke it. To revoke server-side, change your Garmin password — that invalidates the tokens.
Remove from Claude Code
claude mcp remove garmin -s userThat only unregisters the server. To fully remove: also delete
~/.garmin-coach and ~/Developer/garmin-coach.
Troubleshooting
Symptom | Cause / fix |
| Run |
| Refresh token expired/revoked — log in again |
| Wait 15–30 min. Do not retry in a loop |
| Network down, or Garmin maintenance |
Tool returns | Garmin genuinely has no data for that date |
MCP not detected |
|
Set GARMIN_MCP_LOG_LEVEL=DEBUG for verbose stderr logging.
Garmin-MCP
Available Tools
25 toolsgarmin_activities_by_dateC
Activities within a date range.
Inputs: start_date (required), end_date, activity_type. Returns: object
garmin_activityA
Full detail for one activity, including running dynamics and strength sets.
Inputs: activity_id (required), include_sets. Returns: object
garmin_body_batteryC
Body Battery charged/drained plus high/low/latest per day.
Inputs: end_date, start_date. Returns: object
garmin_devicesA
Registered Garmin devices and their ids (needed to push a workout).
Inputs: no named parameters. Returns: object
garmin_exercise_categoriesB
All Garmin strength exercise categories.
Inputs: no named parameters. Returns: object
garmin_exercise_historyA
Previous performance for one exercise across recent strength sessions (for progression).
Inputs: exercise (required), limit, lookback_days. Returns: object
garmin_heart_rateB
Daily resting, min and max heart rate, plus the 7-day resting average.
Inputs: date. Returns: object
garmin_hrvB
Overnight HRV status, last-night average, weekly average and personal baseline.
Inputs: date. Returns: object
garmin_hr_zonesA
The user's Garmin-configured heart-rate zones, including sport-specific profiles.
Always prefer these over calculating zones from age or max HR.
Inputs: no named parameters. Returns: object
garmin_performance_metricsB
VO2 max, lactate threshold, endurance/hill score and race predictions where available.
Inputs: date. Returns: object
garmin_preview_strength_workoutA
Build and show a strength workout WITHOUT uploading it. Always safe; use this to verify structure first.
Inputs: name (required), exercises (required), description. Returns: object
garmin_recent_activitiesA
Most recent activities as compact summaries.
Inputs: limit, activity_type. Returns: object
garmin_recoveryA
Composite recovery view: sleep score, HRV status, resting HR, Body Battery, stress.
Inputs: date. Returns: object
garmin_resolve_exerciseA
Resolve an exercise name to its Garmin category/exercise pair, with suggestions on a miss.
Inputs: name (required). Returns: object
garmin_scheduled_workoutsC
Workouts scheduled on the Garmin calendar.
Inputs: end_date, start_date. Returns: object
garmin_search_exercisesB
Search Garmin's strength exercise catalog for valid category/exercise identifiers.
Inputs: term (required), limit. Returns: object
garmin_sleepA
Sleep score, stages, SpO2, respiration and overnight HRV for one night.
Inputs: date. Returns: object
garmin_strength_setsB
Per-set exercise, reps, weight, duration and rest for a completed strength activity.
Inputs: activity_id (required). Returns: object
garmin_stressB
All-day stress: average, max, and minutes spent at each stress level.
Inputs: date. Returns: object
garmin_todayA
Daily summary: steps, calories, intensity minutes, resting HR, stress, Body Battery.
Inputs: date. Returns: object
garmin_training_readinessB
Training Readiness score/level with its sleep, HRV, recovery-time and load inputs.
Inputs: date. Returns: object
garmin_training_statusA
Training Status, acute/chronic load, ACWR, load focus and VO2 max.
Inputs: date. Returns: object
garmin_workoutA
Full step-by-step detail of one saved workout.
Inputs: workout_id (required). Returns: object
garmin_workoutsA
List saved workouts in the Garmin workout library.
Inputs: limit. Returns: object
garmin_workout_step_formatsA
What Garmin's workout model supports, and where it cannot express a programming rule.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools map to a distinct Garmin metric or resource, and the descriptions clearly separate daily summaries, sleep, HRV, stress, recovery, readiness, and training status. A couple of composite tools overlap in content—recovery vs readiness, training status vs performance metrics—but the descriptions are specific enough to avoid serious misselection.
All tools share a clear garmin_ prefix and mostly follow a resource-oriented naming pattern. Some verbs appear inconsistently (search_exercises, resolve_exercise, preview_strength_workout) compared to noun-only names, but the overall pattern remains predictable and readable.
At 25 tools, this sits right at the heavy end of the borderline range. Each tool maps to a real Garmin endpoint, but the set includes several overlapping composite views and could likely be consolidated without losing capability.
The read side is comprehensive for health metrics and activities, but the workout workflow is incomplete: preview_strength_workout explicitly avoids uploading, and devices mentions needing IDs to push a workout, yet no tool actually pushes, saves, schedules, or edits a workout. This is a significant dead end for the stated coaching purpose.
Maintenance
Related MCP Connectors
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Log meals, water, and weight to Garmin Connect from Claude or ChatGPT.
Garmin Connect MCP server for ChatGPT, Claude and any AI agent: list activities, download FIT file, read sleep and HRV, get training status, create workout and schedule workout in your own Garmin Connect account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Garmin Connect yourself; Cotlet does not store your password and you need no Garmin Connect API key. About the official Garmin Connect API: Yes, in part (checked 27 Oct 2026). Garmin reopened its Connect Developer Program on 21 Oct 2026. Setup and FAQ: https://cotlet.dev/integrations/garmin-api-mcp-server
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects Garmin watch data to Claude Desktop, allowing users to ask natural language questions about their health and activity data from Garmin Connect.-
- FlicenseAqualityDmaintenanceExposes your Garmin Connect data (activities, sleep, recovery, training status) to Claude in read-only mode.7-
- AlicenseAqualityBmaintenanceProvides Claude Code and Claude Desktop with safe, read-only access to your local Garmin training data, readiness decisions, run details, and trends so you can get coaching advice in natural language.1543 PyPI11MIT
- AlicenseAqualityBmaintenanceDaash connects Garmin Connect to ChatGPT and Claude. Your assistant reads your runs, splits, sleep, HRV, Body Battery and recovery, and writes structured workouts and whole training plans to your Garmin calendar, so they're on your watch at the next sync. Free, hosted, open source. Works on free Claude.267MIT