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

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