garmin-health-mcp
Unofficial, read-only MCP server for the Garmin Connect Personal API.
Unofficial, not affiliated with Garmin. Single-user and self-hosted only: a Personal API key may only be used by its owner. Do not run this as a shared or hosted service.
Lets Claude (or any MCP client) read your own sleep, HRV, heart rate, stress, Body Battery, weight, nutrition and activities, including laps, splits and time in heart-rate zones from the original FIT files. It uses Garmin's official, key-based Personal API, so there is no password login and no scraping. See docs/capabilities.md for what each endpoint returns.
Requirements
- uv (it installs Python 3.13 for you if needed)
- A Garmin Connect Personal API key: create one at https://connect.garmin.com/app/settings/personalApiToken (only one key can exist at a time; choose its lifetime there)
Setup
Store the key in the system keyring (macOS Keychain, Windows Credential Locker or the Secret
Service on Linux). setup verifies it with one call before saving it:
uvx garmin-health-mcp setup
uvx garmin-health-mcp setup --delete removes it again. The key is looked up in this order:
GARMIN_PERSONAL_API_KEY_FILE, then GARMIN_PERSONAL_API_KEY, then the keyring (service
garmin-health-mcp). It is never printed, logged or written to .env. Garmin's bearer token is
cached with mode 0600 in GARMIN_HEALTH_MCP_STATE_DIR (default ~/.config/garmin-health-mcp/,
mode 0700).
Use with Claude
The server runs over stdio: your MCP client starts it when needed.
Claude Code:
claude mcp add --scope user garmin-health -- uvx garmin-health-mcp
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS),
then restart Claude Desktop:
{
"mcpServers": {
"garmin-health": {
"command": "uvx",
"args": ["garmin-health-mcp"]
}
}
}
If Claude Desktop cannot find uvx, use its full path (which uvx). The server is named
garmin-health, so it can run next to another Garmin MCP server without tool name clashes.
Remote access (claude.ai and the Claude mobile app)
garmin-health-mcp serve --http serves Streamable HTTP at /mcp, protected by a built-in
single-user OAuth 2.1 server: one static client (no dynamic registration), PKCE S256, login with
password + TOTP, 1-hour access tokens, rotating 30-day refresh tokens with reuse detection, and
garmin-health-mcp auth revoke-all as an emergency brake. Without --http it runs stdio with no
auth, as before.
- Auth layer: mcp-owner-auth
- Design and threat model: docs/security.md
- VPS + Docker + Cloudflare Tunnel + claude.ai setup: docs/deployment.md
Tools
All tools are read-only. Dates are YYYY-MM-DD; single-day tools default to today and range tools
to the last 7 days (at most 1 year).
| Tool | Data |
|---|---|
get_sleep |
one night in detail: stages, sleep score and factors, HR, SpO2, respiration, sleep need |
get_sleep_summaries |
compact sleep summary per night over a range |
get_hrv / get_hrv_summaries |
HRV status, last-night average, baseline (optional 5-min readings) |
get_body_battery |
charged/drained, level over the day, events with impact |
get_stress |
daily stress level and time per stress band |
get_steps |
daily steps, distance, goal |
get_daily_summaries |
one overview per day: movement, calories, HR, intensity minutes, stress, Body Battery, respiration, pulse ox |
get_heart_rate |
resting HR, 7-day average, min/max, hourly min/avg/max (optional raw samples) |
get_heart_rate_zones |
zone floors per sport and the HR values used |
get_spo2 |
SpO2 averages and hourly averages |
get_fitness_age |
fitness age and its components |
get_weight / get_weight_goals |
weigh-ins and goals |
get_hydration / get_food_logs |
logged water and food |
get_wellness_activity_summaries |
wellness activities |
get_profile_settings |
units, locale, time zone (no name or other personal data) |
search_activities |
activities with training effect, training load and time in HR zones |
get_activity / get_activity_workouts |
one activity in detail and its planned workout |
get_activity_laps |
laps from the FIT file: pace, GAP, HR, cadence, power, ascent, intensity |
get_activity_splits |
even splits (per km or any distance) computed from the recorded data |
get_activity_time_in_hr_zones |
time in zones from recorded HR, with current or recorded zones |
get_activity_summary_stats |
session stats incl. running dynamics, power, respiration, RPE |
Menstrual-cycle data is off by default; set GARMIN_HEALTH_MCP_ENABLE_CYCLE=1 to add
get_menstrual_cycle.
Not available through the Personal API: training readiness, training status, race predictions, VO2 max, calendar and workouts. See docs/capabilities.md.
FIT-file analysis
The four get_activity_* analysis tools download the activity's original FIT file once and cache
it in <state dir>/fit/<activity_id>.fit (directory 0700, files 0600; it is health data). It is
decoded with Garmin's FIT SDK. Splits and zone times
exclude paused time; elevation uses a 1.5 m hysteresis against barometer noise; running cadence is
reported in steps/min. Raw record streams and GPS positions are never returned. Delete the cache
directory at any time to free space.
What the server does to responses
- Time: every GMT timestamp (epoch ms or naive string) becomes ISO 8601 in
GARMIN_HEALTH_MCP_TZ(defaultEurope/Copenhagen). TheGMTsuffix is dropped from the key and the duplicate...Localfield is removed. - Noise and privacy:
nulland empty fields, names, display names, profile/owner/device IDs, profile image URLs and GPS start/end coordinates are removed. - Size: long series (heart rate, SpO2, HRV readings) are summarized; raw samples are opt-in.
- Reliability: HTTP 401 triggers one token refresh; 429/5xx and network errors are retried
with exponential backoff and jitter (3 attempts,
Retry-Afterhonoured); date ranges are split into chunks the API accepts. - Logs: method, path and status only. Response bodies are health data and are never logged.
Contributing
See CONTRIBUTING.md. Test fixtures are synthetic: scripts/anonymize.py keeps
the structure of real responses but replaces every identifier and value.
Disclaimer
Unofficial project, not affiliated with or endorsed by Garmin. Garmin Connect is a trademark of Garmin Ltd. Use your own Personal API key for your own data only, within Garmin's terms. This is not medical software.
Credits
- garmin-connect-personal-api-python and the FIT Python SDK by Garmin (Apache-2.0)
- MCP Python SDK
License
Apache-2.0, see LICENSE.
Metadata
Release files for garmin-health-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| garmin_health_mcp-0.1.0.tar.gz | 31.2 kB | With provenance | Details for garmin_health_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| garmin_health_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for garmin_health_mcp-0.1.0-py3-none-any.whl |
Total release size: 65.6 kB
Release files / garmin_health_mcp-0.1.0.tar.gz
| Download URL | garmin_health_mcp-0.1.0.tar.gz |
|---|---|
| Size | 31.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
973de56bf6babad2212c577291504cf7a65658945a1cd1453811f26570697f7d
|
|
BLAKE2b-256 checksum How to use checksums |
28231e34913387f3d83af420451f53841b7fb0fcc22ba4104e04bd7f86a606b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / garmin_health_mcp-0.1.0-py3-none-any.whl
| Download URL | garmin_health_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 34.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d3fb4b569e078aba7b6ac6e922690dd94005e7cee7f5b547436be63de1384a3
|
|
BLAKE2b-256 checksum How to use checksums |
14826348d73e79c2b09a2ddd72b52832c7b6a9e2e3c86b1ff54b81a351f106b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for garmin-health-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for garmin_health_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.