Skip to main content
Glama

Zone Two

Your training log, in conversation. An MCP server that reads your own Garmin Connect data — sleep, HRV, training readiness, activities, body composition — so Claude can answer questions about it directly.

zonetwo.vercel.app · not affiliated with Garmin.

Authentication, and the caveat

Garmin's official Health API is only issued under a commercial partner agreement, so this uses the same private endpoints the Garmin Connect app does, via garminconnect. That works well for your own account and is what every Garmin integration of this kind does, but it is unsupported by Garmin: endpoints can change without notice, and aggressive polling can get an account rate-limited.

You log in once, interactively. Credentials are exchanged for OAuth tokens that are cached on disk and last about a year; the server itself never sees a password and never logs in. That split is deliberate — MFA prompts cannot be answered over an MCP stdio connection, so a server that tried to log in would just hang.

Related MCP server: GC-MCP

Install (Claude Desktop)

Download zonetwo.mcpb from zonetwo.vercel.app or the latest release, and open it. Claude Desktop shows an install dialog asking for your Garmin email and password. Nothing else is needed — no Python, no terminal, no config files.

If your account uses two-step verification, Garmin emails you a code the first time Claude reads your data. Paste it into the conversation and Claude will finish signing in. The code lasts 30 minutes, and the saved token then keeps you signed in for about a year.

Your password is used once, to obtain that token. It is stored by Claude Desktop's own configuration, not by this server, and is only re-used if the token is ever rejected.

Setup (from source)

Requires uv and Python 3.11+.

git clone https://github.com/alchemist-s/zonetwo.git
cd zonetwo
uv sync
uv run zonetwo login     # prompts for email, password, and MFA code if enabled
uv run zonetwo status    # confirms the tokens work

login must run in a real terminal — it prompts for a password and, if your account has MFA, a code. It cannot run through a non-interactive shell (such as Claude Code's ! prefix), and says so rather than failing with a traceback.

With MFA off, credentials can come from the environment instead:

GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=... uv run zonetwo login

Garmin rate-limits login attempts by IP and can answer 429 on the first strategy the client tries. The library falls back across several; if the whole attempt fails that way, wait a few minutes rather than retrying immediately.

Tokens land in ~/.garminconnect (override with GARMINTOKENS), written 0600 in a 0700 directory.

Wire it into Claude Code

claude mcp add zonetwo --scope user -- uv --directory /absolute/path/to/zonetwo run zonetwo

Use an absolute path — the stored config does not expand ~. --scope user makes the server available in every project; without it the default local scope binds it to whichever directory you ran the command from.

Wire it into Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/zonetwo", "run", "zonetwo"]
    }
  }
}

If uv is not on the launcher's PATH, use its absolute path — which uv.

Tools

Dates accept YYYY-MM-DD, today, yesterday, or -7d. Omitting a date means today; omitting a range means the last seven days.

Tool

What it returns

garmin_training_history

Weekly volume, longest run and pace over N weeks — the input for a plan

garmin_create_workout

Build a structured session (intervals, pace targets) and optionally schedule it

garmin_schedule_workout

Put an existing workout on a date

garmin_scheduled_workouts

What's on the calendar this month

garmin_unschedule_workout

Take a session off the calendar, keeping the workout

garmin_delete_workout

Delete a saved workout (plans only — never recorded activities)

garmin_list_workouts

Workouts saved on the account

garmin_export_activities

Activities in a date range as CSV

garmin_briefing

Sleep, HRV, stress, readiness, Body Battery and daily totals in one call

garmin_whoami

Account name and unit preferences

garmin_devices

Registered devices and last sync

garmin_daily_summary

Steps, calories, floors, stress, body battery for a day

garmin_sleep

Stages, sleep score, overnight SpO2 and HRV

garmin_heart_rate

Resting/min/max plus daily average

garmin_hrv

Overnight HRV against your baseline

garmin_stress

Time spent in each stress band

garmin_body_battery

Charge and drain per day over a range

garmin_steps

Daily totals, or 15-minute buckets via intraday_date

garmin_spo2 / garmin_respiration

Pulse ox and breathing rate

garmin_intensity_minutes

Moderate and vigorous minutes

garmin_training_readiness

Readiness score and its contributing factors

garmin_training_status

Status, acute/chronic load balance, VO2 max

garmin_vo2max

VO2 max, fitness age, heat/altitude acclimation

garmin_race_predictions

Predicted 5K / 10K / half / marathon times

garmin_personal_records

PRs by activity type

garmin_activities

Recent activities, newest first

garmin_activities_by_date

Activities in a date range

garmin_last_activity

The most recent activity

garmin_activity

One activity in detail (raw=true for chart samples)

garmin_activity_splits

Per-lap splits

garmin_activity_weather

Weather during an activity

garmin_weight

Weigh-ins and body composition

garmin_api_get

Any Garmin API path, for what the above do not cover

Units travel in the field name

Garmin reports distances in metres, durations in seconds, speeds in metres per second and body mass in grams, all unlabelled. A bare "weight": 74500 reads as kilograms to anything summarising it, and "averageSpeed": 2.75 reads as km/h. So fields are renamed to carry their unit — distanceMeters, durationSeconds, averageSpeedMetersPerSecond, weightKg — and grams are converted, because that one is wrong rather than merely ambiguous. Foot-based activities also get a derived pace ("5:59 min/km"), which is the number a runner actually reads.

Rate limits

Garmin answers 429 rather than queuing, per IP. Calls are capped at three in flight and retried with exponential backoff and jitter; the semaphore is released before sleeping, so one throttled call does not stall unrelated ones. A 429 that survives the retry budget reaches the caller as a message saying to wait, not as a generic failure.

Why the responses are trimmed

Garmin's payloads are built for a dashboard: one night of sleep carries thousands of per-minute samples, and a 20-activity list runs past 100 kB of mostly-null fields. Every tool returns a compact projection and keeps the raw payload behind raw=true. Anything still over ~60 kB comes back as an explicit truncated marker rather than cut-off JSON — truncated JSON reads as complete data that happens to end early, and gets summarised as fact.

What you get depends on your watch

Nothing here is tied to a particular account — log in with yours and it works. But Garmin computes different metrics on different hardware, and the API returns an empty response rather than an error for the ones your device does not support. On a Venu 3, for instance, garmin_training_readiness returns a literal [] and garmin_training_status comes back with every field null: those are Forerunner/Fenix features. zonetwo check reports that as none rather than ok, so you can tell "my watch doesn't do this" from "this is broken".

What it may change

Two kinds of write, with different rules, because they carry different risk.

Plans — creating, scheduling and unscheduling workouts — are always available. They are additive, reversible, and the reason the server exists. Deleting a saved workout is allowed for the same reason: a plan is a draft.

Records — renaming an activity, logging weight or hydration — are opt-in via ZONETWO_ENABLE_WRITES=1, because they edit history rather than intent.

Recorded activities can never be deleted. No such tool exists at any setting. Plans are drafts; history is history.

Writing workouts

garmin_create_workout takes steps a model can plausibly write, and translates them into Garmin's nested format:

{
  "name": "6 x 800m",
  "steps": [
    {"kind": "warmup", "length": "10min"},
    {"repeat": 6, "steps": [
      {"kind": "interval", "length": "800m", "pace": "4:30-4:20"},
      {"kind": "recovery", "length": "90s"}
    ]},
    {"kind": "cooldown", "length": "10min"}
  ],
  "schedule_date": "2026-09-25"
}

Lengths are distances (800m, 5km, 3mi) or times (10min, 90s, 1h); min is parsed before m, so a ten minute warmup is never ten metres. Paces are minutes per kilometre and become the speed bands Garmin expects.

Privacy

Everything runs on your own computer. Requests go straight from your machine to Garmin: there is no server operated by the author, no telemetry, no analytics and no error reporting. (The project website counts page views with Vercel Web Analytics; the server you install reports nothing.)

Your password is used once, to obtain an access token. The token is saved at ~/.garminconnect (mode 0600 inside a 0700 directory) and the password is not used again unless that token is rejected — after about a year, or if you change your Garmin password. The password is never written to disk by this server, never logged, and goes nowhere except Garmin's own sign-in service.

Your health data is fetched on demand and never cached. Note that anything you ask about becomes part of your Claude conversation, which Anthropic processes under their privacy policy.

Scope. Read-only unless GARMIN_MCP_ENABLE_WRITES=1 (or the equivalent install option). Even then it can only rename an activity and record weight or hydration — no tool for deleting anything exists in this server.

Removing it. Uninstall the extension, delete ~/.garminconnect, or change your Garmin password to invalidate the token from Garmin's side.

Not intended for use by anyone under 16.

Troubleshooting

  • "No Garmin tokens…" — run zonetwo login.

  • Tokens rejected — they expire after about a year, and a password change invalidates them. zonetwo login --force.

  • Rate-limited — Garmin throttles per account. Wait a few minutes; avoid looping over long date ranges a day at a time.

  • Today's numbers look wrong — Garmin only has what the watch last synced to your phone.

  • China accounts — zonetwo login --china.

Testing

Four levels, cheapest first.

1. Offline suite — no account, no network.

uv run pytest

Runs against a stub shaped like real Garmin payloads. Covers date parsing, response shaping, every tool's projection logic, and the error paths.

2. Live smoke test — one command, hits your real account.

uv run zonetwo login     # once
uv run zonetwo check

check calls every read-only tool through the real MCP dispatch path and prints one line each:

  garmin_sleep                 ok    {"date": "2026-09-20", "sleepTimeSeconds": 27000, …}
  garmin_hrv                   none  (no data for this date)
  garmin_activity_weather      FAIL  Garmin returned 500

23/24 tools responded (1 with no data), 0 failed.

none is not a failure — it means your device does not record that metric, or has not synced it for that date. Use --date 2026-09-19 to test against a day that has definitely synced; today is often partial.

3. MCP Inspector — poke individual tools in a browser.

uv run mcp dev src/zonetwo/server.py:mcp --with-editable .

Opens a UI where you can list tools, read their schemas, and call them with your own arguments. Needs npx. The --with-editable . matters: the Inspector runs the server in its own environment, which otherwise lacks garminconnect.

4. End to end in Claude Code.

claude mcp add zonetwo --scope user -- uv --directory /absolute/path/to/zonetwo run zonetwo
claude mcp list          # should show garmin as connected

Then ask something that needs real data — "how did I sleep last night?", "what was my longest run this month?", "is my HRV trending down?" — and check the numbers against the Garmin Connect app.

To test the write tools, add -e GARMIN_MCP_ENABLE_WRITES=1 to the claude mcp add command.

Available Tools

35 tools
garmin_activitiesRecent activitiesB
Read-only

Most recent activities, newest first. activity_type filters e.g. running, cycling.

Inputs: limit, offset, activity_type. Returns: result

garmin_activities_by_dateActivities in a date rangeB
Read-only

Activities within a date range (default: last 7 days), oldest first.

Inputs: end, start, activity_type. Returns: result

garmin_activityActivity detailA
Read-only

One activity in detail. raw=true returns the full payload including chart samples.

Inputs: activity_id (required), raw. Returns: object

garmin_activity_splitsActivity splitsC
Read-only

Per-lap splits for an activity.

Inputs: activity_id (required).

garmin_activity_weatherActivity weatherC
Read-only

Weather recorded during an activity.

Inputs: activity_id (required). Returns: object

garmin_api_getDirect Garmin API requestA
Read-only

Call any Garmin Connect API path directly (read-only GET).

For endpoints the dedicated tools do not cover. Paths look like '/usersummary-service/usersummary/daily/{displayName}?calendarDate=2026-09-19'. Prefer a dedicated tool when one exists — this returns unshaped payloads.

Inputs: path (required).

garmin_body_batteryBody BatteryB
Read-only

Body Battery charge and drain per day over a date range (default: last 7 days).

Inputs: end, start. Returns: result

garmin_briefingMorning briefingA
Read-only

Morning snapshot in one call: sleep, HRV, Body Battery, readiness, stress and RHR.

Fetches each section concurrently so answering "how am I doing today?" costs
one round trip instead of six. A section that fails is named in
``sectionsUnavailable`` rather than failing the whole briefing, and a
section the device does not record simply reports its own note.

Returns the numbers only — no training advice. Read readiness, HRV and Body
Battery together rather than any one alone.

Inputs: date. Returns: object

garmin_create_workoutCreate a workoutA

Create a structured running workout on Garmin, optionally scheduling it.

Steps are plain objects, in order. Each needs a ``kind`` (warmup, run,
interval, recovery, rest, cooldown) and a ``length`` — a distance like
"800m", "5km" or a time like "10min", "90s". Optionally add ``pace``
("4:30" or a range "4:30-4:20", minutes per kilometre) or
``heart_rate_zone`` (1-5), and a ``note``.

Repeats nest: ``{"repeat": 6, "steps": [{"kind": "interval", "length":
"800m", "pace": "4:30-4:20"}, {"kind": "recovery", "length": "90s"}]}``.

Once scheduled it appears on the watch on that date.

Inputs: name (required), steps (required), description, schedule_date. Returns: object

garmin_daily_summaryDaily summaryB
Read-only

Whole-day wellness rollup: steps, calories, distance, floors, stress, body battery.

Inputs: date. Returns: object

garmin_delete_workoutDelete a saved workoutA
Destructive

Delete a saved workout. Only affects plans — recorded activities cannot be deleted.

Inputs: workout_id (required). Returns: object

garmin_devicesYour devicesA
Read-only

List the Garmin devices registered to the account, newest sync first.

Inputs: no named parameters. Returns: result

garmin_export_activitiesExport activities as CSVA
Read-only

Export activities in a date range as CSV — the export Garmin makes awkward.

One header row then one row per activity, newest last. Narrow the range if the response comes back truncated.

Inputs: end, start, activity_type. Returns: result

garmin_heart_rateHeart rateA
Read-only

Heart rate for a day. Summary gives min/max/resting; raw adds the 2-minute series.

Inputs: raw, date. Returns: object

garmin_hrvHeart rate variabilityB
Read-only

Overnight heart rate variability: last-night average, baseline and status.

Inputs: date. Returns: object

garmin_intensity_minutesIntensity minutesB
Read-only

Moderate and vigorous intensity minutes for a day, against the weekly goal.

Inputs: date. Returns: object

garmin_last_activityMost recent activityD
Read-only

The most recently recorded activity.

Inputs: no named parameters. Returns: object

garmin_list_workoutsSaved workoutsA
Read-only

List the workouts saved on the Garmin account, newest first.

Inputs: limit. Returns: result

garmin_personal_recordsPersonal recordsB
Read-only

Personal records across activity types.

Inputs: no named parameters.

garmin_race_predictionsRace time predictionsA
Read-only

Predicted race times for 5K, 10K, half and full marathon.

Inputs: no named parameters. Returns: object

garmin_respirationBreathing rateB
Read-only

Breathing rate for a day: waking, sleeping, highest and lowest breaths per minute.

Inputs: date. Returns: object

garmin_scheduled_workoutsScheduled workoutsB
Read-only

List workouts scheduled in a given month (defaults to the current one).

Inputs: year, month.

garmin_schedule_workoutSchedule a workoutB

Put an existing workout on the calendar for a given date.

Inputs: date (required), workout_id (required). Returns: object

garmin_sleepSleepA
Read-only

Sleep for the night ending on the given date: stages, score and overnight vitals.

Inputs: raw, date. Returns: object

garmin_spo2Blood oxygenA
Read-only

Pulse oximetry for a day: average and lowest overnight SpO2.

Inputs: date. Returns: object

garmin_stepsStepsA
Read-only

Daily step totals over a range, or 15-minute buckets for one day via intraday_date.

Inputs: end, start, intraday_date.

garmin_stressStressB
Read-only

All-day stress: average, max and time spent in each stress band.

Inputs: date. Returns: object

garmin_submit_mfa_codeFinish signing in to GarminA

Finish signing in to Garmin with the one-time code it emailed.

Only needed when a Garmin tool has just reported that a code was sent. The code is valid for 30 minutes; afterwards the saved tokens last about a year and this is not asked for again.

Inputs: code (required). Returns: object

garmin_training_historyTraining history by weekA
Read-only

Weekly training volume over recent weeks — the input for writing a plan.

Returns one row per week (distance, sessions, longest run, average pace) plus overall totals, in a single call. Use this before designing a plan rather than fetching activities one range at a time.

Inputs: weeks, activity_type. Returns: object

garmin_training_readinessTraining readinessC
Read-only

Training readiness score for a day, with the factors that drove it.

Inputs: date.

garmin_training_statusTraining statusB
Read-only

Training status, acute/chronic load balance and VO2 max as of a date.

Inputs: date. Returns: object

garmin_unschedule_workoutUnschedule a workoutA

Remove a scheduled workout from the calendar. The workout itself is kept.

Inputs: scheduled_workout_id (required). Returns: object

garmin_vo2maxVO2 max and fitness ageA
Read-only

VO2 max, fitness age and heat/altitude acclimation as of a date.

Inputs: date. Returns: object

garmin_weightWeight and body compositionA
Read-only

Weigh-ins over a date range (default: last 7 days), with body composition where recorded.

Inputs: end, start.

garmin_whoamiGarmin accountA
Read-only

Identify the signed-in Garmin account and its unit preferences.

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

    B3/5.0

    Scored across 35 tools

    Disambiguation4/5

    Each tool targets a distinct Garmin data source or action, and the metric tools are clearly separated by health domain. The main ambiguity risk is between rollups like garmin_briefing and garmin_daily_summary, and between activity list variants, but the descriptions are specific enough to resolve those.

    Naming Consistency4/5

    The garmin_ prefix and snake_case style are consistent throughout. Reader tools use noun-ish names like garmin_hrv and garmin_steps while action tools use verb_noun names like create_workout and delete_workout; a few outliers like garmin_api_get and garmin_whoami break the pattern but are still predictable.

    Tool Count2/5

    35 tools is well over the 25+ threshold and feels heavy for an agent to navigate, even though the domain is broad. Many health metrics and workout operations are legitimately distinct, but the surface would benefit from consolidation, such as grouping daily wellness metrics into fewer tools.

    Completeness4/5

    The set covers the core Garmin wellness and activity domains thoroughly: health metrics, activity history/detail, personal records, training status, and workout lifecycle management. Minor gaps exist, like no update_workout or activity deletion, but garmin_api_get provides a read-only escape hatch and the main workflows have no dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access and query Garmin Connect health and fitness data, including sleep, HRV, training load, and activities, with an optional coaching plugin for personalized training plans.
      4
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query live Garmin Connect health and fitness data, including daily metrics, activities, sleep analysis, and trends via natural language.
      MIT