Skip to main content
Glama

garmin-mcp

CI License: MIT Python 3.12+ 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 metric or kind selector, 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=1 removes 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 login

2. 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-mcp

Claude 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-mcp

On 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

garmin_status

Login, token lifetimes, last watch sync, time zone, last error

garmin_activities

Activities by date range and type, newest first; limit=0 for the count

garmin_activity

One activity: summary, laps, run/walk or interval splits, weather, HR and power zones, gear, strength sets, training effect, time series

garmin_activity_analysis

From the FIT file: climbs, grades, decoupling, power curve, NP/IF/TSS, R-R HRV, dynamics, Di2

garmin_fit_messages

Every decoded FIT message, paged

garmin_power_curve

Best power for 5 s to 60 min across recent activities, with an FTP estimate

garmin_wellness

One day: summary, sleep, HRV, stress, Body Battery, heart rate, steps, SpO2, respiration, floors, hydration, intensity minutes, events, lifestyle

garmin_training

Readiness, recovery time, training status, load balance, fitness age, VO2max, acclimation, running tolerance, race predictions, lactate threshold, FTP

garmin_trend

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

garmin_body

Weigh-ins, body composition, blood pressure

garmin_profile

Profile, settings, heart-rate and power zones

garmin_devices

Devices, last sync, settings, primary device, solar intake, alarms

garmin_gear

Shoes and bikes, with distance and default activity types

garmin_achievements

Goals, personal records, badges, challenges

garmin_workouts

Saved workouts as readable steps (or raw JSON)

garmin_calendar

Scheduled workouts, races and events, Garmin Coach plans

garmin_nutrition / garmin_food_search

Garmin Connect food log, goals, energy balance; food search

garmin_courses

Courses and their waypoints

garmin_womens_health

Menstrual cycle and pregnancy tracking

garmin_reference

Activity types, event types, strength-exercise catalog, workout format

garmin_api_get

Read-only GET of any Garmin Connect API path

garmin_download

Save an activity (FIT, GPX, TCX, KML, CSV), workout or course to disk

garmin_create_workout

Build a structured workout from simple steps and schedule it

garmin_upload_workouts / garmin_schedule_workouts

Upload Garmin workout JSON; schedule workouts (never twice on a day)

garmin_update_activity / garmin_create_activity

Rename, retype, describe, RPE, feel, gear; add manual activities

garmin_add_weigh_in / garmin_add_body_composition / garmin_add_blood_pressure / garmin_add_hydration

Log body data

garmin_set_hr_zones / garmin_request_reload

Heart-rate zones; reprocess a day

garmin_set_nutrition_goals / garmin_save_custom_food / garmin_log_food

Garmin Connect nutrition

garmin_upload_course

Create a course from a GPX file

garmin_delete

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

GARMIN_MCP_HOME

~/.garmin-mcp

Where the tokens live; use one per account

GARMIN_MCP_TIMEZONE

the account's

IANA time zone for "today" and timestamps

GARMIN_MCP_READ_ONLY

off

1 removes every tool that changes the account

GARMIN_MCP_ENABLED_TOOLS / GARMIN_MCP_DISABLED_TOOLS

all

Comma-separated allow / deny lists

GARMIN_MCP_DOWNLOAD_DIR

~/Downloads/garmin-mcp

Where downloads go

GARMIN_MCP_HTTP

auto

curl_cffi forces the Windows workaround, requests disables it

GARMIN_MCP_CALL_TIMEOUT

90

Seconds per call; 0 disables

GARMIN_MCP_MAX_CHARS

40000

Cap on answer length

GARMIN_MCP_IS_CN

off

1 for garmin.cn accounts (untested)

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 garmin-mcp-auth login again in a terminal

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 GARMIN_MCP_HTTP=curl_cffi, and avoid VPNs and datacenter networks

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

garmin-mcp-auth status tests the saved login; garmin_status shows the last error

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 analysis
  • The 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_delete deletes 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 account

Issues 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

MIT

Available Tools

39 tools
garmin_achievementsC
Read-only

Goals, personal records, badges (earned, available, in progress) and challenges (adhoc, badge, available, unfinished, virtual).

Inputs: kind (required), limit, start, status.

garmin_activitiesA
Read-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_activityC
Read-only

One activity in as much depth as needed, one or more sections per call.

Inputs: activity_id (required), detail, points, sections.

garmin_activity_analysisA
Read-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_getA
Read-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_bodyA
Read-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_calendarB
Read-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_coursesA
Read-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_deleteA
Destructive

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_devicesB
Read-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_downloadB
Idempotent

Save an activity, workout or course as a file on this computer.

Inputs: id (required), kind (required), format, output_dir, +1 more.

garmin_fit_messagesB
Read-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_gearC
Read-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_nutritionA
Read-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_curveA
Read-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_profileB
Read-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_referenceA
Read-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_statusA
Read-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_trainingA
Read-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_trendA
Read-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_wellnessA
Read-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_healthA
Read-only

Pregnancy summary, menstrual data for one date, or the menstrual calendar for a range.

Inputs: kind (required), date, end_date, start_date.

garmin_workoutsA
Read-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

    B3.3/5.0

    Scored across 39 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    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
      154 PyPI
      6
      MIT
    • 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
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects 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