garmin-health-mcp
Read-only access to a user's Garmin Connect data through Garmin's official Personal API — sleep, HRV, resting heart rate, Body Battery, stress, calories, activities, training load, fitness profile and intraday metrics. Adds a local history layer on top: time series and PNG charts for dozens of daily metrics, Garmin-style acute/chronic load and load ratio, CTL/ATL/TSB, Load Focus, recovery-time estimates and a per-user-calibrated training readiness score, plus morning check-ins, weekly reports, dashboard data bundles and a raw endpoint escape hatch.
garmin-health-mcp
An MCP server that gives Claude (or any MCP client) your Garmin data — sleep, HRV, resting heart rate, Body Battery, stress, calories, activities, training load and recovery — through Garmin's official Personal API, launched on 21 October 2026. No password scraping, no reverse-engineered endpoints: you create a personal API key in Garmin Connect, and this server uses it read-only.
On top of the raw data it keeps a local history so it can do the things the API doesn't:
Time series and charts for ~45 daily metrics, with rolling averages and trends.
Training load the way Garmin shows it: acute load, chronic load and their ratio (with Garmin's 0.8–1.5 optimal band), plus fitness / fatigue / form (CTL / ATL / TSB) and an approximate Load Focus.
A readiness estimate built like Garmin's Training Readiness (sleep, recent sleep, HRV status, recovery time, acute load, recent stress) that calibrates to your watch as you log Garmin's scores.
Dashboard-ready data and a built-in prompt for building an interactive dashboard artifact.
Unofficial project, not affiliated with or endorsed by Garmin. "Garmin" is a trademark of Garmin Ltd.
What you need
A Garmin account with a Personal API key (it starts with
GCDC_). Create one in Garmin Connect's settings under the Personal API / Connect Developer Program Personal tier. Keys last a year; only one can exist at a time.uv(the installers below use it to run the server).
Related MCP server: garmin-mcp
Install
Claude Desktop (one click)
Download garmin-health-mcp.mcpb from the latest release
and open it. Claude Desktop asks for your API key and stores it in the OS keychain.
Claude Code (plugin)
/plugin marketplace add jonpojonpo/garmin-health-mcp
/plugin install garmin-health@garmin-health-mcpClaude Code asks for your API key when the plugin is enabled and keeps it in your system keychain. You can
also leave it empty and provide the key as GARMIN_API_KEY, or in the file Garmin's own client uses:
mkdir -p ~/.config/garmin && printf '%s' 'GCDC_...' > ~/.config/garmin/connect-personal-api-key
chmod 600 ~/.config/garmin/connect-personal-api-keyThe plugin also installs three skills (see Skills).
OpenAI Codex CLI
codex mcp add garmin-health -- uvx --from git+https://github.com/jonpojonpo/garmin-health-mcp garmin-health-mcpPut the key in ~/.config/garmin/connect-personal-api-key as above, or add --env GARMIN_API_KEY=GCDC_...
before the -- (that stores it in plain text in ~/.codex/config.toml). The first start downloads the
dependencies; if Codex reports a startup timeout, add startup_timeout_sec = 60 under
[mcp_servers.garmin-health] in ~/.codex/config.toml.
ChatGPT (web and app) only connects to MCP servers over the internet, so it needs a hosted or tunnelled copy of the server; that isn't packaged yet.
Any MCP client
{
"mcpServers": {
"garmin-health": {
"command": "uvx",
"args": ["--from", "git+https://github.com/jonpojonpo/garmin-health-mcp", "garmin-health-mcp"],
"env": { "GARMIN_API_KEY": "GCDC_..." }
}
}
}The first call backfills 210 days of history (about 35 API requests); after that only stale days are
fetched. Call sync(days=365) for a longer history.
Tools
Tool | What it gives you |
| Sleep, HRV vs baseline, resting HR vs 7-day mean, Body Battery at wake, recovery hours left, training load and form, readiness estimate |
| Record the Training Readiness score your watch shows; the estimate calibrates to it |
| Estimate vs logged Garmin scores, morning by morning |
| Daily load, acute/chronic/ratio, CTL/ATL/TSB, weekly totals with HR- and power-zone minutes, load by sport |
| Low aerobic / high aerobic / anaerobic split of recent load |
| Activity list with load, Training Effect, HR, power, zones; full detail for one |
| Cycling power bests 5 s–60 min, FTP (set or estimated), zones, W/kg |
| Everything per day; active/resting/total calories; week-by-week rollups |
| Any daily metric as aligned series with stats, or as a PNG chart |
| One JSON bundle for building dashboards |
| 5-minute HRV, intraday HR and Body Battery, fitness age and HR zones |
| Manual backfill; raw access to other Personal API endpoints |
Prompts: Morning briefing, Weekly review, Build a dashboard.
Skills
Tools fetch the data; skills tell Claude what to do with it. They ship with the Claude Code plugin, and the
folders in skills/ can also be added to Claude Desktop or claude.ai as custom skills.
Skill | Use it for |
| "How recovered am I? Should I train today?" Reads the numbers against your own baseline, logs Garmin's readiness when you mention it, and ends with one concrete session |
| "Make me a dashboard." The recipe for an interactive page from |
| "Plan my week." Sets a load target from your chronic load, sizes sessions from your own history, and keeps the load ratio in Garmin's 0.8–1.5 band |
Models and how far to trust them
Garmin's Personal API does not expose Training Readiness, Training Status, recovery time, acute load or Load Focus (those paths return 404). This server models them from the data that is exposed, and the constants were fitted against the Garmin Connect app's own screens for one rider on 25 October 2026:
Model | How | Check against Garmin |
Acute load | Exponentially weighted daily training load (time constant 5.1 days, x1.284) | 1,046 vs Garmin 1,019; tracks Garmin's 4-week chart within about ±50 |
Chronic load | Last 28 days of load / 4 | 813 vs centre of Garmin's optimal band ~820 |
Load Focus | Each activity's load split by aerobic vs anaerobic Training Effect, aerobic part by HR-zone time | 1036 / 1611 / 605 vs Garmin 1118 / 1519 / 607 |
Recovery time | Hours from Training Effect (TE 5 ≈ 60 h, TE 3.5 ≈ 34 h), overlapping sessions stack 30% | 50 h vs Garmin 46 h |
Readiness | Six 0–100 factors → 40% weighted mean + 60% soft minimum, so one bad factor drags it down as Garmin's does | 31 vs Garmin 25 before calibration |
One rider is not a validation set. Readiness corrects itself per user: log Garmin's score with
log_garmin_readiness (or just tell Claude the number) and it applies an offset, then a fitted slope once
four scores are logged. If your numbers drift from Garmin's in other places, please open an issue with
both values.
Privacy
Your data goes only between your computer and Garmin's API. The API key is read from the environment
(Claude Desktop keeps it in the OS keychain) or from a local file, and is never logged or returned by a
tool. The short-lived access token and the history database live in ~/.garmin-health-mcp/ (override with
GARMIN_HEALTH_DATA_DIR). Delete that folder to remove everything. Whatever your MCP client does with tool
results (for example, sending them to a model) follows that client's own privacy terms.
Other Personal API servers
Garmin's Personal API is new and several community servers appeared within days. If you only want the raw endpoints, Mason-Levyy/garmin-personal-mcp wraps all of them one-to-one; braydenabo/garmin-mcp keeps a local archive with trends and charts; zigmund/garmin-papi-mcp is a remote server with OAuth for claude.ai and ChatGPT. This project focuses on the layer on top: training load, recovery, a calibrated readiness estimate, and a one-click Claude Desktop install.
Development
uv sync
uv run pytest
uv run ruff check
GARMIN_API_KEY=GCDC_... uv run garmin-health-mcp # stdio server
npx @anthropic-ai/mcpb pack # build the .mcpb bundleEndpoint list and the key-to-token exchange follow Garmin's own reference client,
garmin-connect-personal-api-python, as documented in
cluffa/garmin-api-cli.
License
MIT
Available Tools
21 toolsactivitiesBRead-only
Activities, newest first: type, duration, distance, Garmin training load, aerobic/anaerobic Training Effect and label, active kcal, HR, power (avg / normalised / best 20 min), elevation, minutes in HR zones 1-5 and power zones 1-7, and modelled recovery hours. activity_type filters by Garmin type key, e.g. running, cycling, virtual_ride.
Inputs: end, limit, start, activity_type. Returns: result
activityBRead-only
Full Garmin detail for one activity (Garmin's summary DTO).
Inputs: activity_id (required).
api_getARead-only
Raw GET against the Personal API for data without a tool, e.g. /weight-service/weight/range/{start}/{end}, /usersummary-service/stats/hydration/daily/{start}/{end}, /wellness-service/wellness/daily/spo2acclimation/{date}, /userprofile-service/userprofile/settings. Paths outside Garmin's allowlist return 404 (Training Readiness/Status, PRs, workouts, badges).
Inputs: path (required), params.
caloriesCRead-only
Daily calories burned: active, resting, total, and from recorded activities, with averages.
Inputs: end, days.
chartBRead-only
PNG chart of up to 6 daily metrics as stacked panels on a shared date axis: points or bars for raw values, a line for the rolling mean. HRV gets its balanced band shaded; readiness_est shows logged Garmin scores. Good sets: ["hrv","rhr","sleep_score","readiness_est"], ["load","acute_load","ctl","tsb"], ["active_kcal","steps","stress"].
Inputs: metrics (required), end, days, smooth.
dailyCRead-only
Everything known per day: sleep, HRV, resting HR, Body Battery, stress, calories, steps, training load, form, recovery and readiness estimate.
Inputs: end, days. Returns: result
dashboard_dataBRead-only
Compact JSON bundle for building a dashboard (e.g. an HTML artifact with charts): today's snapshot, aligned daily series for the key metrics, weekly rollups, load focus, the last 30 days of activities and the power profile. Embed it as data in the page rather than re-deriving numbers. Series values are null where Garmin has no data.
Inputs: days.
fitness_profileBRead-only
Garmin fitness age (with the changes that would lower it) and heart-rate zones.
Inputs: no named parameters.
hrv_nightBRead-only
One night's HRV in detail, including the 5-minute readings.
Inputs: day.
intradayARead-only
Intraday curve for one day. what: "heart_rate" (resting/min/max plus HR about every 12 minutes) or "body_battery" (level through the day plus Garmin's charge/drain events).
Inputs: day, what.
list_metricsARead-only
Daily metrics available to timeseries, chart and dashboard_data.
Inputs: no named parameters. Returns: object
load_focusBRead-only
Approximate Garmin Load Focus: training load split into low aerobic, high aerobic and
anaerobic over the last days days.
Inputs: days.
log_garmin_readinessAIdempotent
Record the Training Readiness score Garmin shows (0-100), stored locally, so the estimate calibrates to it (an offset at first, a fitted slope from 4 scores). Log it whenever the user mentions their Garmin readiness. Readiness drops after workouts, so log it close to when it was read.
Inputs: score (required), day, note.
morning_checkARead-only
Recovery snapshot: last night's sleep, HRV vs baseline, resting HR vs its 7-day mean, Body Battery at wake, modelled recovery hours left, training load (acute/chronic ratio, fitness/fatigue/form), yesterday's calories and stress, and a readiness estimate shaped like Garmin's Training Readiness (sleep, recent sleep, HRV status, recovery time, acute load, recent stress). For today it is evaluated now, so it counts this morning's workouts. Garmin's real Training Readiness is not in the API: when the user mentions their Garmin readiness score, call log_garmin_readiness so the estimate calibrates to it.
Inputs: day.
power_profileBRead-only
Cycling power: FTP (set with set_athlete, otherwise estimated as 95% of best 20-min
power), best powers 5 s-60 min over days and the last 28 days, W/kg if weight is set,
Coggan power zones in watts, and 5-min / 60-min to FTP ratios.
Inputs: days.
readiness_historyBRead-only
Per-morning readiness estimate (at wake) next to its main inputs and any Garmin readiness scores logged, to judge how well the model tracks Garmin.
Inputs: end, days. Returns: result
set_athleteBIdempotent
Store FTP and body weight locally (used for power zones and W/kg).
Inputs: ftp_w, weight_kg.
syncARead-only
Refresh the local history for the last days days. Other tools sync on their own;
use this for a first long backfill (e.g. 365 days) or after the watch syncs.
Inputs: days, force.
timeseriesBRead-only
Aligned daily series for chosen metrics (see list_metrics) with an optional rolling
mean of smooth days, plus per-metric last/mean/min/max and linear trend per week.
Examples: hrv, rhr, sleep_score, bb_wake, stress, active_kcal, load, acwr, ctl, tsb, readiness_est.
Inputs: metrics (required), end, days, smooth.
training_loadCRead-only
Training load: daily load, Garmin-style acute load and acute:chronic ratio (Garmin's optimal band is 0.8-1.5), fitness/fatigue/form (CTL/ATL/TSB), a status label, weekly totals (sessions, hours, distance, load, active kcal, minutes per HR zone and power zone), and load by sport.
Inputs: end, days.
weekly_reportBRead-only
Week-by-week (Monday start): averages of sleep score and hours, HRV, resting HR, stress, Body Battery at wake, active kcal and steps; totals of training hours and load; end-of-week fitness and form.
Inputs: weeks. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target clearly distinct slices of data (per-activity detail vs activities list, power vs load, readiness logging vs readiness history). Some overlap exists among the aggregate/view tools (daily, weekly_report, timeseries, dashboard_data, chart) and between morning_check and daily, but the descriptions do a good job of separating their intended uses.
All names are consistently snake_case and readable. The only deviation is a mix of noun-only names (activities, daily, calories, intraday, sync) and verb-led names (log_garmin_readiness, set_athlete, list_metrics, load_focus), which is minor and does not impede understanding.
21 tools is on the high side, but each maps to a distinct Garmin data domain (sleep/HRV, load, activities, power, readiness, charts, sync). There is mild redundancy among the aggregation/view tools (chart, dashboard_data, timeseries, weekly_report), but the surface is not bloated arbitrarily.
Coverage is broad: recovery, sleep, HRV, load, activities, power, readiness estimation/calibration, plus a raw api_get escape hatch for gaps like weight/hydration/SpO2. The main gaps are native Garmin Training Readiness/Status (explicitly unavailable) and write/fitness-management operations, but core read workflows are covered.
Maintenance
Related MCP Connectors
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects to Garmin Connect and exposes fitness and health data (activities, steps, heart rate, sleep, body composition) to MCP-compatible clients like Claude.MIT
- AlicenseAqualityCmaintenanceConnects MCP clients to Garmin Connect data, enabling queries about activities, sleep, heart rate, body battery, and training status.162MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to Garmin Connect data through OAuth, including activities, sleep, HRV, body battery, training status, and scheduled TrainingPeaks workouts.-
- AlicenseNot gradedqualityCmaintenanceConnects to Garmin Connect to expose fitness and health data to MCP-compatible clients, enabling activity management, health metrics, training analytics, workout creation, and more via natural language.MIT