Skip to main content

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.

CI PyPI

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

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.

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 (default Europe/Copenhagen). The GMT suffix is dropped from the key and the duplicate ...Local field is removed.
  • Noise and privacy: null and 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-After honoured); 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

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)

Source distribution for garmin-health-mcp 0.1.0
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)

Table of built distributions (wheels) for garmin-health-mcp 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page