Garmin Connect MCP Server

A local stdio MCP server that gives Claude direct access to your Garmin Connect data. Built on the garminconnect library (garth-backed OAuth). Read-only — no data is written back to Garmin.

---

Tools (32)

Daily Health

| Tool | Data | |------|------| | get_sleep | Sleep stages (deep/light/REM/awake), score, duration, respiration, SpO2 | | get_hrv | Overnight HRV, 5-min readings, baseline, status (Balanced/Unbalanced/Low) | | get_body_battery | Charge/drain events, start/end levels throughout the day | | get_stress | Average stress, max stress, time in each stress band | | get_heart_rate | Resting HR, min/max, timestamped HR timeline | | get_spo2 | Blood oxygen average, min, max, overnight continuous readings | | get_respiration | Breathing rate average, min, max throughout day and overnight | | get_steps_and_activity | Steps, floors, distance, calories, intensity minutes | | get_hydration | Fluid intake vs daily goal | | get_daily_summary | All-in-one snapshot: steps, calories, HR, stress, Body Battery, intensity |

Training & Fitness

| Tool | Data | |------|------| | get_training_readiness | Readiness score (0–100) with component breakdown (sleep, HRV, load, recovery) | | get_training_status | Status label, acute/chronic load, load focus, VO2 max trend | | get_vo2max_and_fitness_metrics | VO2 max estimate, fitness age | | get_lactate_threshold | Threshold HR and pace | | get_race_predictions | Predicted finish times: 5K / 10K / half marathon / marathon | | get_endurance_score | Garmin's aerobic capacity score over a date range | | get_hill_score | Elevation handling ability over a date range | | get_running_tolerance | Acute/chronic load ratio and injury risk signals over a date range | | get_personal_records | PRs across all activity types | | get_progress_summary | Training volume trends between two dates, grouped by activity type |

Activities

| Tool | Data | |------|------| | get_activities | List of recent activities: type, date, distance, duration, avg HR, calories, Training Effect, load | | get_last_activity | Most recent activity with full summary stats | | get_activity_detail | Full detail for a single activity by ID: Training Effect, aerobic/anaerobic load, pace, cadence | | get_activity_splits | Per-km splits with pace, HR, and elevation | | get_activity_hr_zones | Time spent in each HR zone for an activity | | get_activity_streams | Time-series chart data (up to 2000 points): cadence, HR, speed, power, elevation | | get_activity_power_zones | Time in each power zone (meaningful once real power data is available) |

Trends & History

| Tool | Data | |------|------| | get_sleep_history | Sleep scores and stage breakdown over past N days (default 14, max 28) | | get_hrv_history | Overnight HRV values over past N days | | get_body_battery_history | End-of-day Body Battery levels over past N days | | get_weekly_summary | 7-day rollup: steps, calories, intensity minutes, stress, sleep averages |

Body

| Tool | Data | |------|------| | get_weight | Weight and body composition over a date range |

---

Setup

1. Clone and create a virtual environment

git clone <repo-url>
cd Garmin-MCP
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Authenticate (first time only)

python setup_auth.py

Enter your Garmin Connect email and password when prompted. If you have MFA enabled you'll be asked for your authenticator code. OAuth tokens are saved to ~/.garminconnect/ — your password is never stored.

Tokens auto-refresh indefinitely. Re-run only if you revoke the session or change your password.

Note on rate limiting: Garmin aggressively rate-limits login attempts from non-mobile IPs. If you see 429 errors, wait 5–10 minutes before retrying. Logging into Garmin Connect in your browser immediately beforehand can help.

3. Add to Claude Desktop config

Open your Claude Desktop config file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add the garmin entry under mcpServers:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/Garmin-MCP/.venv/bin/python",
      "args": ["/absolute/path/to/Garmin-MCP/garmin_server.py"]
    }
  }
}

Use absolute paths. Find them by running echo $(pwd)/.venv/bin/python from inside the project folder.

Fully quit Claude Desktop (Cmd+Q) and reopen it.

4. Verify

Ask Claude: "What was my sleep score last night?" or "Show me my training status."

---

Notes

No credentials in the config — authentication is handled entirely via the saved token file in ~/.garminconnect/. Nothing sensitive lives in the Claude Desktop config.

Race predictions and training status context — Garmin's algorithm needs sustained threshold efforts to calibrate well. During injury recovery or low-volume phases, labels like "Unproductive" and inflated race predictions are common artefacts of limited signal, not accurate assessments of fitness. Use these numbers alongside context rather than at face value.

Power data — get_activity_power_zones and power fields in get_activity_streams are only meaningful for activities with real power data recorded (e.g. BikeErg sessions via ERG Logbook). Garmin's estimated FTP is extrapolated from VO2 max and is unreliable without actual power measurements.

Activity streams and cadence — get_activity_streams returns Garmin's raw chart data. Note that Garmin records running cadence as single-foot steps per minute; multiply by 2 for total cadence (steps/min).

---

Troubleshooting

Token expired errors — run python setup_auth.py again to re-authenticate.

429 Too Many Requests — Garmin rate-limits login attempts heavily. Wait 5–10 minutes and try again.

MFA prompt not appearing — try logging out of all active Garmin Connect sessions in your browser first, then re-run setup_auth.py.

Tools not showing in Claude — make sure you fully quit Claude Desktop (Cmd+Q, not just closing the window) before restarting. Check that the paths in the config are absolute and correct.

Empty results from some tools — some endpoints (endurance score, hill score, running tolerance) require a minimum activity history to return data. If you've recently set up your device, these may return empty until Garmin has enough data to compute them.

---

Dependencies

• garminconnect >= 0.2.22
• mcp >= 1.0.0