Zone Two
Zone Two is a read-mostly MCP server that connects Claude to your personal Garmin Connect data and lets it build/schedule running workouts.
Wellness overviews: daily summary, sleep, heart rate, HRV, stress, Body Battery, steps, SpO2, respiration, intensity minutes, weight/body composition, and a combined morning briefing
Training metrics: readiness, training status, VO2 max, race predictions, personal records, and weekly training history
Activity data: list/search recent activities by date range or type, get full activity details, splits, and weather, export activities as CSV, and fetch any Garmin API path directly
Account/device info: identify the signed-in account, unit preferences, registered devices, and last sync
Workout planning: create structured workouts (warmup, intervals, recovery, cooldown), schedule/unschedule them, list saved/scheduled workouts, and delete saved workouts (plans only)
Authentication: interactive login with optional MFA code submission; read-only by default, with writes only when explicitly enabled and no ability to delete recorded activities
Provides tools for accessing and managing Garmin Connect data, including activities, sleep, HRV, workouts, and body composition, allowing AI agents to query and plan training.
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., "@Zone Two How was my sleep and HRV 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.
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 worklogin 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 loginGarmin 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 zonetwoUse 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 |
| Weekly volume, longest run and pace over N weeks — the input for a plan |
| Build a structured session (intervals, pace targets) and optionally schedule it |
| Put an existing workout on a date |
| What's on the calendar this month |
| Take a session off the calendar, keeping the workout |
| Delete a saved workout (plans only — never recorded activities) |
| Workouts saved on the account |
| Activities in a date range as CSV |
| Sleep, HRV, stress, readiness, Body Battery and daily totals in one call |
| Account name and unit preferences |
| Registered devices and last sync |
| Steps, calories, floors, stress, body battery for a day |
| Stages, sleep score, overnight SpO2 and HRV |
| Resting/min/max plus daily average |
| Overnight HRV against your baseline |
| Time spent in each stress band |
| Charge and drain per day over a range |
| Daily totals, or 15-minute buckets via |
| Pulse ox and breathing rate |
| Moderate and vigorous minutes |
| Readiness score and its contributing factors |
| Status, acute/chronic load balance, VO2 max |
| VO2 max, fitness age, heat/altitude acclimation |
| Predicted 5K / 10K / half / marathon times |
| PRs by activity type |
| Recent activities, newest first |
| Activities in a date range |
| The most recent activity |
| One activity in detail ( |
| Per-lap splits |
| Weather during an activity |
| Weigh-ins and body composition |
| 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 pytestRuns 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 checkcheck 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 connectedThen 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 toolsgarmin_activitiesRecent activitiesBRead-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 rangeBRead-only
Activities within a date range (default: last 7 days), oldest first.
Inputs: end, start, activity_type. Returns: result
garmin_activityActivity detailARead-only
One activity in detail. raw=true returns the full payload including chart samples.
Inputs: activity_id (required), raw. Returns: object
garmin_activity_splitsActivity splitsCRead-only
Per-lap splits for an activity.
Inputs: activity_id (required).
garmin_activity_weatherActivity weatherCRead-only
Weather recorded during an activity.
Inputs: activity_id (required). Returns: object
garmin_api_getDirect Garmin API requestARead-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 BatteryBRead-only
Body Battery charge and drain per day over a date range (default: last 7 days).
Inputs: end, start. Returns: result
garmin_briefingMorning briefingARead-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 summaryBRead-only
Whole-day wellness rollup: steps, calories, distance, floors, stress, body battery.
Inputs: date. Returns: object
garmin_delete_workoutDelete a saved workoutADestructive
Delete a saved workout. Only affects plans — recorded activities cannot be deleted.
Inputs: workout_id (required). Returns: object
garmin_devicesYour devicesARead-only
List the Garmin devices registered to the account, newest sync first.
Inputs: no named parameters. Returns: result
garmin_export_activitiesExport activities as CSVARead-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 rateARead-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 variabilityBRead-only
Overnight heart rate variability: last-night average, baseline and status.
Inputs: date. Returns: object
garmin_intensity_minutesIntensity minutesBRead-only
Moderate and vigorous intensity minutes for a day, against the weekly goal.
Inputs: date. Returns: object
garmin_last_activityMost recent activityDRead-only
The most recently recorded activity.
Inputs: no named parameters. Returns: object
garmin_list_workoutsSaved workoutsARead-only
List the workouts saved on the Garmin account, newest first.
Inputs: limit. Returns: result
garmin_personal_recordsPersonal recordsBRead-only
Personal records across activity types.
Inputs: no named parameters.
garmin_race_predictionsRace time predictionsARead-only
Predicted race times for 5K, 10K, half and full marathon.
Inputs: no named parameters. Returns: object
garmin_respirationBreathing rateBRead-only
Breathing rate for a day: waking, sleeping, highest and lowest breaths per minute.
Inputs: date. Returns: object
garmin_scheduled_workoutsScheduled workoutsBRead-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_sleepSleepARead-only
Sleep for the night ending on the given date: stages, score and overnight vitals.
Inputs: raw, date. Returns: object
garmin_spo2Blood oxygenARead-only
Pulse oximetry for a day: average and lowest overnight SpO2.
Inputs: date. Returns: object
garmin_stepsStepsARead-only
Daily step totals over a range, or 15-minute buckets for one day via intraday_date.
Inputs: end, start, intraday_date.
garmin_stressStressBRead-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 weekARead-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 readinessCRead-only
Training readiness score for a day, with the factors that drove it.
Inputs: date.
garmin_training_statusTraining statusBRead-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 ageARead-only
VO2 max, fitness age and heat/altitude acclimation as of a date.
Inputs: date. Returns: object
garmin_weightWeight and body compositionARead-only
Weigh-ins over a date range (default: last 7 days), with body composition where recorded.
Inputs: end, start.
garmin_whoamiGarmin accountARead-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
Scored across 35 tools
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.
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.
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.
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
Related MCP Connectors
Explore Garmin activity and health data with your AI assistant.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Ask your AI about your fitness: activities and data from Garmin, COROS, Strava, GPX and more
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables creation, management, and scheduling of Garmin Connect workouts from natural language descriptions, plus viewing activities, calendar data, and weather information from completed workouts.30MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query live Garmin Connect health and fitness data, including daily metrics, activities, sleep analysis, and trends via natural language.MIT
- FlicenseNot gradedqualityDmaintenanceEnables querying your Garmin Connect data including recent activities, detailed metrics, and daily stats through natural language.-