garmin-connect-mcp
Read-only access to a user's own Garmin Connect data via Garmin's official Personal API, exposing tools for daily recovery (sleep, HRV, resting HR, stress, Body Battery, steps), activity lists and details including FIT-derived laps and HR-zone minutes, training volume summaries by week/month, body composition, nutrition, and user profile settings.
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-connect-mcp How's my recovery been over the past two weeks?"
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-connect-mcp
A read-only MCP server for your own Garmin Connect data, built on Garmin's official Personal API (no password, no scraping). It authenticates with a revocable API key you create in Garmin Connect and uses Garmin's own Python client underneath.
Instead of mirroring the API one endpoint per tool, it exposes a few tools shaped around questions, and returns compact, unit-labelled JSON so a whole month fits in context.
Tools
Tool | What it answers | Calls to Garmin |
| Per day: sleep (h, score, stages, bedtime), overnight HRV + 7-day avg, resting HR, stress, Body Battery, steps; plus range averages. ≤ 92 days, default 7. | daily summaries + sleep + HRV, split into 31-day windows, in parallel |
| Sleep sub-scores and Garmin's insight, HRV readings range, Body Battery events (what charged/drained it) | 4 |
| One row per activity: duration, distance, pace/speed, HR, power/NP, TSS/IF, training load, TE, minutes per HR zone | 1 per 45 activities |
| Summary + planned workout; from the FIT file: each leg of a multisport/brick session, every lap, HR-zone minutes | 3–4 |
| Volume per ISO week/month/day split by swim/bike/run/…: sessions, hours, km, elevation, load, TSS, zone minutes (computed locally). Default 8 weeks | 1 per 45 activities |
| Weigh-ins (kg, body fat, muscle, water) and range average | 1 |
| Food log totals, goals, meals; hydration and sweat loss | 2 |
| Units, time zone, training days, HR zones; optional key-expiry warning | 2 |
| Escape hatch for any other Personal API GET (stress series, all-day HR, SpO2, fitness age…), squeezed and capped at 40k chars | 1 |
All tools are annotated read-only. Units are metric and spelled out in the keys
(_km, _min, _bpm, _w, _ms, _kg); run pace is min/km, swim pace min/100 m.
Dates accept YYYY-MM-DD, today or yesterday; sleep and HRV are filed under the
morning you woke up.
Not available from the Personal API (so not here either): training status/readiness, VO2max trend, race predictor, creating or scheduling workouts, writing anything.
Related MCP server: Threshold
Setup
1. Install uv
uv is the only prerequisite — it handles Python and the package in one shot.
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"2. Create a Garmin Personal API key
Garmin Connect web → Settings → Personal API (https://connect.garmin.com/app/settings/personalApiToken). Pick an expiry (max one year), copy the key; it's shown once.
3. Add to your MCP config
macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": ["--from", "git+https://github.com/KaiTries/garmin_connect_mcp", "garmin-connect-mcp"],
"env": {
"GARMIN_PERSONAL_API_KEY": "YOUR-KEY-HERE",
"GARMIN_MCP_TZ": "Europe/Zurich",
"GARMIN_KEY_EXPIRES": "2027-10-28"
}
}
}
}Claude Code:
claude mcp add garmin -- uvx --from git+https://github.com/KaiTries/garmin_connect_mcp garmin-connect-mcp
# then set the key: claude mcp edit garmin (add GARMIN_PERSONAL_API_KEY to env)uvx fetches and caches the package on first run. To update to the latest version later:
uvx --from git+https://github.com/KaiTries/garmin_connect_mcp --reinstall garmin-connect-mcp checkPrefer a secrets file? Store the key at ~/.config/garmin/connect-personal-api-key
(mode 600) and omit GARMIN_PERSONAL_API_KEY from the config. Useful if multiple tools
share the same key or you'd rather not put credentials in the MCP config file.
mkdir -p ~/.config/garmin
printf '%s' 'YOUR-KEY' > ~/.config/garmin/connect-personal-api-key
chmod 600 ~/.config/garmin/connect-personal-api-keyHome server (streamable HTTP)
git clone https://github.com/KaiTries/garmin_connect_mcp
cd garmin_connect_mcp
mkdir -p secrets
printf '%s' 'YOUR-GARMIN-KEY' > secrets/garmin_api_key
openssl rand -hex 32 > secrets/mcp_http_token
chmod 644 secrets/* # the container runs as uid 10001 and must read them
docker compose up -d --buildThe server listens on :8000/mcp; every request except /healthz needs
Authorization: Bearer <contents of secrets/mcp_http_token>. It refuses to bind to a
non-loopback address without a token unless you set GARMIN_MCP_ALLOW_UNAUTHENTICATED=1
(only do that behind a reverse proxy that authenticates). Behind a proxy, set
GARMIN_MCP_ALLOWED_HOSTS to the public host name to enable DNS-rebinding protection.
Claude Code against the server:
claude mcp add --transport http garmin https://garmin.your.lan/mcp --header "Authorization: Bearer $TOKEN"Configuration
Variable | Default | Purpose |
|
| API key source |
| – |
|
| system | Defines "today" |
|
|
|
|
| HTTP bind |
| – | Bearer token for HTTP |
| – | Comma-separated Host names for DNS-rebinding protection |
|
| Seconds per Garmin request |
How it works
Key → 24 h bearer token via Garmin's client (cached in
~/.config/garmin/); a rejected token is renewed once, an expired or deleted key produces a message telling you where to make a new one.Long ranges are split into the windows each endpoint accepts (28 days for stress/steps, 31 for sleep/daily summaries/Body Battery, 365 for HRV; 45 activities per page).
FIT files are parsed with
fitparse; HR-zone minutes integrate per-second records against your Garmin zone floors, ignoring gaps over 10 s (pauses).
Development
git clone https://github.com/KaiTries/garmin_connect_mcp
cd garmin_connect_mcp
uv sync --frozen
uv run pytestTests use payloads shaped after Garmin's OpenAPI models, mocked HTTP for the client layer, a real MCP client session against the server, a synthetic bike→run FIT file, and the HTTP transport in a subprocess.
Available Tools
9 toolsgarmin_api_getARead-onlyIdempotent
Escape hatch: GET any Personal API path and return the JSON, squeezed (nulls and image/ID noise removed, long lists cut). Use only when no other tool covers the data, e.g. /usersummary-service/stats/stress/daily/{start}/{end}, /wellness-service/wellness/dailyHeartRate?date=…, /wellness-service/wellness/daily/spo2acclimation/{date}, /fitnessage-service/fitnessage/v2/{date}, /goal-service/goal/user/effective/weightgoal/{start}/{end}.
Inputs: path (required), params. Returns: result
get_activityARead-onlyIdempotent
One activity in detail: summary metrics, the planned workout it followed, and (from the FIT file) each leg of a multisport session, every lap, and minutes per HR zone.
Inputs: activity_id (required), include_laps. Returns: result
get_body_compositionARead-onlyIdempotent
Weigh-ins per day (weight, body fat, muscle, water, BMI) and the range average. Defaults to the last 90 days.
Inputs: end_date, start_date. Returns: result
get_day_detailARead-onlyIdempotent
Deeper look at one day: sleep score breakdown and Garmin's sleep insight, overnight HRV readings range, and the Body Battery events (sleep charge, activities, stress) that explain the day's drain. Defaults to today.
Inputs: date. Returns: result
get_nutritionARead-onlyIdempotent
Food log for one day from Garmin Connect nutrition (totals, goals, meals) plus hydration intake and estimated sweat loss. Defaults to today.
Inputs: date. Returns: result
get_profileARead-onlyIdempotent
User settings relevant to interpreting data: units, time zone, training days and heart-rate zones per sport.
Inputs: no named parameters. Returns: result
get_recoveryARead-onlyIdempotent
Day-by-day recovery picture: sleep (duration, score, stages, bedtime), overnight HRV and its 7-day average, resting HR, stress, Body Battery and steps, plus range averages. Defaults to the last 7 days; at most 92 days per call.
Inputs: end_date, start_date. Returns: result
get_training_summaryARead-onlyIdempotent
Training volume per week (or month/day) split by sport: sessions, hours, distance, elevation, training load, TSS and HR-zone minutes. Computed by this server from the activity list. Defaults to the last 8 full ISO weeks including the current one.
Inputs: end_date, group_by, start_date. Returns: result
list_activitiesARead-onlyIdempotent
Activities newest first, one compact row each: duration, distance, pace/speed, HR, power, TSS/IF, training load, training effect and time in HR zones. Defaults to the last 30 days.
Inputs: limit, end_date, start_date, activity_type. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes: list_activities vs get_activity, get_training_summary, get_body_composition, get_nutrition, and get_profile are easy to tell apart. The main overlap is get_recovery vs get_day_detail, since both surface sleep, HRV, and Body Battery data, though the range-vs-single-day distinction helps. garmin_api_get is an intentional escape hatch with explicit usage guidance.
Eight of nine tools follow a consistent snake_case verb_noun pattern using get_ or list_ prefixes. garmin_api_get is a minor deviation, but it still uses snake_case and signals its special escape-hatch role. Overall naming is predictable and readable.
Nine tools is well-scoped for a read-only Garmin Connect data server. Each tool covers a distinct data area—recovery, day detail, activities, training, body composition, nutrition, profile—and the escape hatch adds flexibility without bloating the set. No tool feels redundant or superfluous.
The surface covers the core health/fitness domains: recovery, sleep, HRV, activities, training load, body composition, nutrition, and profile. Minor gaps exist for less common metrics like SpO2, fitness age, and goals, but garmin_api_get provides a documented escape hatch for those cases. This is broadly complete for typical agent workflows.
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying your Garmin Connect data including recent activities, detailed metrics, and daily stats through natural language.-
- AlicenseNot gradedqualityBmaintenanceConnects Garmin Connect to AI assistants, answering questions about training, sleep, HRV and recovery with metrics computed in code rather than guessed from raw JSON. Queries daily readiness, training load, activity FIT analysis and personal records through a self-hosted Cloudflare Worker with OAuth.16 npm8MIT
- AlicenseBqualityBmaintenanceProvides local, Keychain-secured access to all 26 Garmin Connect Personal API GET endpoints plus 8 summary tools. Enables users to query sleep, HRV, Body Battery, activities, profile, weight, and other connected health data through their own Personal API key.341Apache 2.0
- AlicenseAqualityBmaintenanceEnables ChatGPT and compatible AI clients to query read-only Garmin Connect data—including sleep, HRV, heart rate, Body Battery, wellness metrics, and activities—through a hosted OAuth-backed MCP connection using a personal API key.2151MIT