garmin-mcp
Integrates with Garmin Connect to access and analyze health, fitness, and training data from Garmin devices. Provides tools for querying sleep, HRV, Body Battery, stress, training readiness, VO2max, activities such as runs and rides, wellness metrics, body composition, gear, achievements, workouts, courses, nutrition, and women's health. Supports detailed activity analysis from FIT files, trend reporting, workout creation and scheduling, and logging body data.
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, and am I ready for intervals 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-mcp
A Model Context Protocol (MCP) server for Garmin Connect. Ask Claude (or any MCP client) about your sleep, HRV, Body Battery, stress, training readiness, VO2max, runs and rides, and have it build structured workouts that sync to your watch.
"How did I sleep last night, and am I ready for intervals today?" "Show the splits and heart-rate zones of my last run." "Plot my HRV and resting heart rate for September." "Build me 6 x 400 m at 3:50-4:05/km for Thursday." "Where did I lose time on the climbs in Sunday's ride?"
It works with any Garmin device that syncs to Garmin Connect (Forerunner, Fenix, Epix, Venu, Vivoactive, Edge, Index scales...). It runs locally on your computer, and your password never reaches the server.
Why this one
Everything, in 39 tools. It covers every one of the 153 tools in Taxuspt/garmin_mcp, mapped one by one in PARITY.md and enforced by a test. Related endpoints sit behind one tool with a
metricorkindselector, so the whole server costs a quarter of the context in every chat.A login that survives Garmin's changes. Built on python-garminconnect 0.3.x, which recovered from Garmin's March 2026 login change. You log in once in a terminal (MFA supported). The server only reuses the saved tokens and never retries a password login, because repeated attempts can lock an account for days.
Answers a model can use. Compact JSON with the unit in every key (
distance_km,avg_hr_bpm,pace_min_km), in your account's time zone, with today's partial data marked. Garmin's unit quirks (grams, RPE ×10, Fahrenheit, knots, centimetres...) are converted in one place and were checked against Garmin Connect on a real account.Deeper analysis. Decodes the original FIT file with Garmin's official FIT SDK: climbs and VAM, time on each grade, aerobic decoupling, power curve, NP/IF/TSS, R-R HRV, running and cycling dynamics, Di2 gear use.
Safe writes. Every tool carries MCP annotations, so clients know which ones change your account. Deletes always preview first.
GARMIN_MCP_READ_ONLY=1removes every write.Windows-proof. A Cloudflare 403 on Windows 11 (python-garminconnect #444) is retried automatically through curl_cffi.
Related MCP server: garmin-mcp
Quick start
You need uv.
1. Log in once, in a terminal. It asks for your Garmin email, password and, if Garmin
sends one, the verification code. Only the tokens are saved, to ~/.garmin-mcp/.
uvx --from git+https://github.com/wiande00/garmin-mcp garmin-mcp-auth login2. Add the server to your MCP client.
Claude Code:
claude mcp add --scope user garmin -- uvx --from git+https://github.com/wiande00/garmin-mcp garmin-mcpClaude Desktop (claude_desktop_config.json; quit Claude Desktop completely before
editing, since it rewrites the file while running):
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": ["--from", "git+https://github.com/wiande00/garmin-mcp", "garmin-mcp"]
}
}
}If Claude Desktop can't find uvx, use its full path (which uvx, or where uvx on
Windows). Other MCP clients take the same command and arguments. To pin a release, add
@v0.1.0 to the git URL.
3. Ask away. Start with "check my Garmin status".
git clone https://github.com/wiande00/garmin-mcp
cd garmin-mcp
uv sync
uv run garmin-mcp-auth login
claude mcp add --scope user garmin -- uv --directory "$PWD" run --quiet garmin-mcpOn Windows with the Microsoft Store edition of Claude Desktop,
scripts\add-to-claude-desktop.cmd registers the server for you: double-click it from
File Explorer, quit Claude Desktop from its tray icon, and it adds the entry and reopens
Claude.
Tools
Tool | What it covers |
| Login, token lifetimes, last watch sync, time zone, last error |
| Activities by date range and type, newest first; |
| One activity: summary, laps, run/walk or interval splits, weather, HR and power zones, gear, strength sets, training effect, time series |
| From the FIT file: climbs, grades, decoupling, power curve, NP/IF/TSS, R-R HRV, dynamics, Di2 |
| Every decoded FIT message, paged |
| Best power for 5 s to 60 min across recent activities, with an FTP estimate |
| One day: summary, sleep, HRV, stress, Body Battery, heart rate, steps, SpO2, respiration, floors, hydration, intensity minutes, events, lifestyle |
| Readiness, recovery time, training status, load balance, fitness age, VO2max, acclimation, running tolerance, race predictions, lactate threshold, FTP |
| A metric over a date range: sleep, HRV, resting HR, steps, stress, calories, Body Battery, training load (acute, chronic, ACWR, form), VO2max, endurance and hill score, weight, totals by sport |
| Weigh-ins, body composition, blood pressure |
| Profile, settings, heart-rate and power zones |
| Devices, last sync, settings, primary device, solar intake, alarms |
| Shoes and bikes, with distance and default activity types |
| Goals, personal records, badges, challenges |
| Saved workouts as readable steps (or raw JSON) |
| Scheduled workouts, races and events, Garmin Coach plans |
| Garmin Connect food log, goals, energy balance; food search |
| Courses and their waypoints |
| Menstrual cycle and pregnancy tracking |
| Activity types, event types, strength-exercise catalog, workout format |
| Read-only GET of any Garmin Connect API path |
| Save an activity (FIT, GPX, TCX, KML, CSV), workout or course to disk |
| Build a structured workout from simple steps and schedule it |
| Upload Garmin workout JSON; schedule workouts (never twice on a day) |
| Rename, retype, describe, RPE, feel, gear; add manual activities |
| Log body data |
| Heart-rate zones; reprocess a day |
| Garmin Connect nutrition |
| Create a course from a GPX file |
| Delete weigh-ins, blood pressure, workouts, scheduled workouts, foods, courses; always previews first |
Five workout templates are also available as MCP resources (workout://templates/...).
Building workouts
garmin_create_workout takes plain steps and emits Garmin's exact workout JSON:
[
{"type": "warmup", "duration": "10:00", "hr_zone": 2},
{"repeat": 6, "steps": [
{"type": "interval", "distance_km": 0.4, "pace_min_km": ["3:50", "4:05"]},
{"type": "recovery", "duration": "1:30"}
]},
{"type": "cooldown", "lap_button": true}
]Each step ends one way (duration, distance_km, reps, lap_button) and has at most
one target (hr_zone, hr_bpm, pace_min_km, speed_kmh, power_w, power_zone,
cadence). Strength steps name an exercise from Garmin's catalog ("exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 80). Running, cycling, swimming, walking, hiking,
strength and more are supported.
Configuration
All optional, as environment variables on the server entry:
Variable | Default | Effect |
|
| Where the tokens live; use one per account |
| the account's | IANA time zone for "today" and timestamps |
| off |
|
| all | Comma-separated allow / deny lists |
|
| Where downloads go |
|
|
|
|
| Seconds per call; |
|
| Cap on answer length |
| off |
|
garmin-mcp --transport streamable-http --port 8765 serves over HTTP on 127.0.0.1 instead
of stdio. That transport has no authentication, so it never listens beyond loopback.
Troubleshooting
Symptom | What to do |
"Not logged in" / "session has expired" | Run |
429 during login | Garmin is rate-limiting. The login command enforces a cooldown (15 min, 60 after a 429); wait it out rather than retrying |
403 on every call | Usually Cloudflare. It is retried through curl_cffi automatically; set |
412 on a write | EU accounts must grant upload consent in Garmin Connect's privacy settings first |
Training status, race predictions empty | A new watch needs a few weeks of activities first; the tools say so |
Anything else |
|
How it works
src/garmin_mcp/
server.py the MCP server: tool names, parameters, descriptions, annotations
cli.py garmin-mcp-auth login | status | logout
auth.py tokens, the login and its cooldown, why a login doesn't work
client.py one Garmin client per process, error translation, cache
transport.py the Windows 403 fallback
units.py every Garmin unit quirk
tools/ what each tool does, testable without MCP
workout_dsl.py the workout step language and checks for raw workout JSON
fit.py FIT decoding (Garmin FIT SDK) and analysisThe server logs in lazily on the first call, so the MCP handshake never waits on Garmin.
Calls run in a worker thread with a timeout, serialised so token refreshes stay safe.
Range views use Garmin's range endpoints where they exist: a 90-day sleep or HRV trend is a few requests, not 90.
Failures keep Garmin's status and text, and each kind gets its own message.
garmin_deletedeletes only a request previewed in the last 15 minutes.
Development
uv sync
uv run pytest # no network: a fake Garmin client and synthetic payloads
uv run ruff check
uv run python scripts/smoke.py # read-only check of every tool against your real accountIssues and pull requests are welcome. For a bug, include the output of garmin_status
(it holds no secrets).
Credits
python-garminconnect by cyberjunky does the hard part: logging in and talking to Garmin Connect.
Taxuspt/garmin_mcp defined the feature set, and its issue tracker was the best guide to what goes wrong. Endpoints that python-garminconnect doesn't wrap follow its source.
Garmin FIT SDK decodes activity files.
Disclaimer
This is an unofficial project, not affiliated with or endorsed by Garmin. It uses the same private API as the Garmin Connect apps, which Garmin can change at any time, and Garmin's terms of use don't cover third-party access. Use it with your own account, at your own risk.
License
Available Tools
39 toolsgarmin_achievementsCRead-only
Goals, personal records, badges (earned, available, in progress) and challenges (adhoc, badge, available, unfinished, virtual).
Inputs: kind (required), limit, start, status.
garmin_activitiesARead-only
List activities, newest first: id, type, start time, distance, time, pace or speed, heart rate, training load and effect. Pass an id to garmin_activity for detail.
Inputs: page, limit, end_date, start_date, +1 more.
garmin_activityCRead-only
One activity in as much depth as needed, one or more sections per call.
Inputs: activity_id (required), detail, points, sections.
garmin_activity_analysisARead-only
Deeper analysis from the activity's original FIT file, beyond what Garmin Connect shows. Manual activities have no FIT file.
Inputs: activity_id (required), include.
garmin_add_blood_pressureC
Record a blood-pressure reading (mmHg).
Inputs: systolic (required), diastolic (required), when, notes, +1 more.
garmin_add_body_compositionC
Record a full body-composition measurement (as a smart scale would).
Inputs: weight_kg (required), bmi, when, basal_met, +9 more.
garmin_add_hydrationC
Log water intake in Garmin Connect's hydration tracker.
Inputs: ml (required), when.
garmin_add_weigh_inC
Record a weigh-in in Garmin Connect.
Inputs: weight (required), unit, when.
garmin_api_getARead-only
Read-only escape hatch: GET any Garmin Connect API path and return the raw JSON. Use only when no other garmin_ tool covers what is needed.
Inputs: path (required), params.
garmin_bodyARead-only
Body measurements over a period (default today): weigh_ins (each one, with body composition when a smart scale sent it), body_composition (entries plus averages), blood_pressure. Ids in the answer are what garmin_delete needs.
Inputs: kind (required), end_date, start_date.
garmin_calendarBRead-only
The training calendar, looking forward by default. Scheduled entries carry the scheduled_id that garmin_delete kind=scheduled_workouts needs.
Inputs: include, end_date, start_date.
garmin_coursesARead-only
Saved courses (routes): the list, or one course with its waypoints.
Inputs: course_id.
garmin_create_activityB
Add a manual activity (one the watch didn't record), in the account's time zone.
Inputs: type_key (required), duration_minutes (required), date, name, +2 more.
garmin_create_workoutA
Build a structured workout and save it to Garmin Connect (it syncs to the watch). Each step ends one way (duration, distance_km, reps or lap_button) and has at most one target (hr_zone, hr_bpm, pace_min_km, speed_kmh, power_w, power_zone, cadence). Strength steps name a catalog exercise. See the workout://templates resources. Confirm the plan with the user first.
Inputs: name (required), sport (required), steps (required), description, +2 more.
garmin_deleteADestructive
Permanently delete from Garmin Connect: weigh_ins (all on the date, or the ids given), blood_pressure, workouts, scheduled_workouts (unschedule), custom_food, food_log, course. Without confirm it only previews. With confirm=true it deletes only what was previewed in the last 15 minutes. There is no undo.
Inputs: kind (required), ids, date, confirm.
garmin_devicesBRead-only
Watches and other devices: list, last_used (and when it last synced), settings, primary (training device), solar (charging intake on a date), alarms.
Inputs: date, kind, device_id.
garmin_downloadBIdempotent
Save an activity, workout or course as a file on this computer.
Inputs: id (required), kind (required), format, output_dir, +1 more.
garmin_fit_messagesBRead-only
Every field of the activity's FIT file, decoded with Garmin's FIT SDK, paged. For questions no other tool answers.
Inputs: activity_id (required), limit, offset, message_types, +1 more.
garmin_food_searchBRead-only
Search foods, with each serving's id and macros (what garmin_log_food needs).
Inputs: limit, query, start, source.
garmin_gearCRead-only
Shoes, bikes and other gear: status, default activity types, total distance.
Inputs: include_stats.
garmin_log_foodB
Log food to Garmin Connect's food log: a saved food by id and serving, or a quick add by name and calories, to Garmin Connect's food log.
Inputs: meal_time (required), name, fat_g, source, +8 more.
garmin_nutritionARead-only
Garmin Connect's food log. food_log, meals and settings (calorie and macro goals) for one date; summary (per-day totals) and energy_balance (intake against burn, and what the weight trend implies) over up to 61 days.
Inputs: kind (required), date, end_date, start_date.
garmin_power_curveARead-only
Best power for 5 s to 60 min across recent activities, with an FTP estimate (95 % of the best 20 minutes). Downloads one file per activity, so it is slow.
Inputs: activity_type, num_activities.
garmin_profileBRead-only
The account owner. profile: body measurements, VO2max, lactate threshold, usual sleep window. settings: Garmin's raw user settings. hr_zones: heart-rate zones in bpm per sport. power_zones: power zones.
Inputs: sport, section.
garmin_referenceARead-only
Lookup lists: activity_types (type keys, grouped), event_types (for activities), strength_exercises (Garmin's exercise catalog; search with query), food_serving_units (for custom foods).
Inputs: kind (required), query.
garmin_request_reloadA
Ask Garmin to reprocess a day's data (when a day's numbers look stuck or wrong).
Inputs: date (required).
garmin_save_custom_foodC
Create or update a custom food (grams per serving, sodium in mg).
Inputs: name (required), calories (required), fat, brand, +10 more.
garmin_schedule_workoutsA
Put saved workouts on the calendar (a week plan at once if needed). A workout already on that day is not added twice.
Inputs: items (required).
garmin_set_hr_zonesA
Change heart-rate zone settings for a sport. With method max_hr and a new max_hr the floors are recalculated at 50/60/70/80/90 %. Confirm with the user first.
Inputs: sport, max_hr, method, resting_hr, +2 more.
garmin_set_nutrition_goalsC
Set Garmin Connect's daily calorie and macro goals from a date.
Inputs: date, fat_g, carbs_g, protein_g, +2 more.
garmin_statusARead-only
Login and connection check: who is logged in, how long the saved login lasts, when the watch last synced, and the last error. Call this first when another Garmin call fails, or to see how current the data is.
Inputs: no named parameters.
garmin_trainingARead-only
Training state on a day (default today). readiness: every training-readiness reading that day, with its factors; morning_readiness: the one after waking. recovery_time: hours still needed. status: training status, weekly load, acute/chronic load, ACWR, form, VO2max. load_balance: four-week aerobic low/high and anaerobic load against targets. Also fitness_age, vo2max, acclimation (heat/altitude), running_tolerance, race_predictions (5k to marathon), lactate_threshold, cycling_ftp.
Inputs: metric (required), date, detail.
garmin_trendARead-only
A metric across a date range, one row per day (or week). stats (steps + calories), steps, calories, stress, intensity_minutes, sleep (per night), hrv (per night), respiration, resting_hr, body_battery, weight, training_load (acute, chronic, ACWR, form per day), vo2max (the dates it changed), running_tolerance, endurance_score, hill_score, lactate_threshold, progress (activity totals by type). Most allow up to a year; respiration and daily stress/intensity minutes 31 days, training_load 90 days.
Inputs: metric (required), end_date, start_date, aggregation.
garmin_update_activityA
Edit an activity: rename, retype, describe, set event type, RPE, feel, or gear. Only the fields given change. Confirm with the user first.
Inputs: activity_id (required), rpe, feel, name, +5 more.
garmin_upload_courseC
Create a private course in Garmin Connect from a GPX file.
Inputs: gpx_path (required), name, description, activity_type.
garmin_upload_workoutsA
Upload workouts written directly in Garmin's JSON. All are checked before any is uploaded (ids vs keys, nested targets, power targets, repeat groups). Prefer garmin_create_workout unless the exact JSON matters.
Inputs: workouts_json (required).
garmin_wellnessARead-only
One day of wellness data.
summary: steps, calories, intensity minutes, resting/min/max HR, stress, body battery,
SpO2, respiration, active and sedentary time.
sleep: the night that ENDED on date (date=today is last night): times, stages,
score, HRV, resting HR, SpO2. hrv: the same night's HRV, baseline and status.
body_battery: charged/drained, high/low and the events that moved it.
stress, heart_rate, steps: day totals plus an hour-by-hour profile.
Also resting_hr, spo2, respiration, floors, hydration, intensity_minutes,
events (auto-detected movement), lifestyle (lifestyle logging).
Inputs: metric (required), date, detail.
garmin_womens_healthARead-only
Pregnancy summary, menstrual data for one date, or the menstrual calendar for a range.
Inputs: kind (required), date, end_date, start_date.
garmin_workoutsARead-only
Saved workouts: the list, or one workout's steps (duration or distance, targets, repeats, strength exercises).
Inputs: raw, workout_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Tools are organized around distinct Garmin domains (activities, wellness, training, nutrition, body, devices), and paired tools like garmin_activities/garmin_activity are clearly list-vs-detail. A few boundaries blur: garmin_add_weigh_in vs garmin_add_body_composition, garmin_create_workout vs garmin_upload_workouts, and the three 'escape hatch' tools (garmin_api_get, garmin_fit_messages, garmin_activity_analysis) all claim to be for cases no other tool covers.
All names use a uniform garmin_ prefix and snake_case, with predictable verb_noun forms for mutations (add_, create_, set_, log_, delete_) and noun forms for readers. The mix of noun-only readers (garmin_profile, garmin_gear) and verb_noun tools (garmin_add_weigh_in) is a minor inconsistency but internally readable.
39 tools exceeds the comfortable 3-15 range and lands in heavy territory. The Garmin Connect domain is genuinely broad enough to justify many of them, but multiple escape-hatch/analysis tools and a few overlapping add_ tools push it past what most agents can navigate efficiently.
Coverage spans read, create, update, schedule, upload, download, and delete across activities, wellness, training, nutrition, body, devices, gear, workouts, calendar, courses, achievements, and women's health. Every apparent data domain has a corresponding mutation or lifecycle operation, and the preview-then-confirm delete pattern closes the loop for destructive actions.
Maintenance
Related MCP Connectors
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
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).
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.28154 PyPI6MIT
- 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
- 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
- AlicenseNot gradedqualityNot gradedmaintenanceConnects Garmin training data to Claude so it can read recent activities, wellness and recovery signals, and upcoming calendar events. It also lets Claude create, update, and delete structured workouts that sync through intervals.icu to Garmin Connect and onto the user's watch.MIT