garmin-mcp

A local MCP server that exposes your Garmin Connect activity, health, and training data (activities, HRV, sleep, heart rate, stress, body battery, training readiness, HR/power zones, lactate threshold, FTP, VO2max, personal records, workouts, scheduled workouts, and training plans) as tools inside Claude Desktop.

It talks directly to the live Garmin Connect API via the garminconnect library. Data is read-only — nothing is ever written back to Garmin.

How auth works

Garmin login happens in two separate places on purpose:

• scripts/setup_auth.py — an interactive script you run yourself in a terminal. It logs in with your email/password, prompts you for an MFA code if Garmin asks for one, and saves the resulting session token to ~/.garmin_mcp/tokens.
• The MCP server (src/garmin_mcp/server.py), launched headlessly by Claude Desktop, only ever loads and silently refreshes that cached token. It never prompts for MFA — Claude Desktop gives it no terminal to prompt on, and blocking on stdin there would hang tool calls. If the cached session is missing or has expired, tool calls fail with an error telling you to re-run setup_auth.py.

Your Garmin password is stored in the macOS keychain (item/service garmin-mcp, viewable in Keychain Access), never written to a file. Only your Garmin login email (not secret) is saved, in ~/.garmin_mcp/config.json.

Setup

1. Install dependencies:

   cd garmin_mcp
   uv sync
   

2. Run the one-time interactive login:

   uv run python scripts/setup_auth.py
   

   Enter your Garmin Connect email and password (the password is then stored in the keychain for next time). Enter the MFA code when prompted. On success you'll see a confirmation and the token cache path.

3. Register the server with Claude Desktop by editing ~/Library/Application Support/Claude/claude_desktop_config.json and adding (alongside any other mcpServers entries):

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }
   

4. Fully quit Claude Desktop (Cmd+Q, not just close the window) and reopen it. The tools/hammer icon should list the garmin tools.

Tools

Tool	Description
list_activities	Recent activities, most recent first (paginated, optional type filter)
get_activity	Full detail for one activity: summary + per-metric time series
get_activity_splits	Lap/split data for one activity
get_heart_rate	Daily resting HR + intraday HR timeline
get_daily_stats	Steps, calories, resting HR, distance, floors, intensity minutes
get_sleep	Sleep stages, duration, sleep score
get_hrv	Heart rate variability
get_body_battery	Body Battery energy reserve over a date range
get_stress	All-day stress level
get_training_readiness	Training Readiness score and contributing factors
get_profile	Identity, unit prefs, personal settings (max HR, resting HR, weight, height, VO2max), HR zones and power zones per sport
get_lactate_threshold	Running lactate threshold: heart rate, power, and speed
get_cycling_ftp	Latest cycling Functional Threshold Power
get_ftp_history	Historic FTP for a sport over a date range
get_max_metrics	Max-metric data (e.g. VO2max) over a date range
get_resting_heart_rate	Daily resting heart rate trend over a date range
get_fitness_age	Garmin Fitness Age for a given date
get_personal_records	Personal records
list_workouts	Saved workout templates, most recent first (paginated)
get_workout	Full structure of one workout: segments, targets, intervals
get_scheduled_workouts	Calendar of workouts scheduled for a given month
get_scheduled_workout	Detail for one scheduled workout instance
list_training_plans	Training plans
get_training_plan	Details for a specific training plan
get_adaptive_training_plan	Details for a specific adaptive training plan

All date parameters take YYYY-MM-DD and default to today.

Troubleshooting

A tool call returns a "Garmin session error" / "run setup_auth.py" message. Your cached refresh token expired or was revoked (this happens occasionally, e.g. after a password change or long period of inactivity). Re-run:

uv run python scripts/setup_auth.py

Rate limited. Garmin Connect will occasionally rate-limit rapid requests; the underlying library retries transient failures automatically, but if you see a rate-limit error, wait a bit and try again.

Verifying the server directly, outside Claude Desktop:

uv run mcp dev src/garmin_mcp/server.py

opens the MCP Inspector so you can call each tool by hand and check its output/schema.

Project layout

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login