Garmin Connect MCP server

An MCP server for strength training on Garmin Connect. Design a session in conversation with an AI assistant, push it to your watch, and read back what you actually lifted.

Unofficial. Not affiliated with, endorsed by, or supported by Garmin. Garmin and Garmin Connect are trademarks of Garmin Ltd. This project talks to Garmin's private workout-service endpoints through the reverse-engineered python-garminconnect client, so Garmin can change or break it without notice. Use at your own risk, and check your own obligations under Garmin's terms of service.

Everything runs locally. Your credentials stay on your machine and only ever go to Garmin.

Why this exists

Garmin Connect will not import workout .FIT files — FIT import only works for completed activities, not planned workouts. Your options are the Connect web UI by hand, or the same private endpoint the web app itself calls. This takes the second route and puts an MCP interface on it, so a workout can come out of a conversation instead of twenty minutes of clicking.

Tools

delete_workout is the only destructive tool.

Setup

Requires Python 3.12 or newer (garminconnect 0.3.x needs it).

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh creates .venv/ in the project directory, installs dependencies, and copies .env.example to .env. Nothing is installed system-wide. If your newest Python has no wheels for a dependency yet, override it:

PYTHON=python3.13 ./setup.sh

Fill in .env with your Garmin login, then authenticate once:

./.venv/bin/python garmin_login.py

This step is interactive on purpose. Garmin may ask for an MFA code, and the MCP server has no terminal to ask on — it would simply hang. The login caches tokens to ~/.garminconnect, and the server reuses them silently from then on. Re-run it only if the server reports the session expired.

Verify the build without touching the network:

./.venv/bin/python garmin_mcp.py --self-test

Connect it to a client

Claude Desktop

Add to claude_desktop_config.json — on macOS at ~/Library/Application Support/Claude/, on Windows at %APPDATA%\Claude\:

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

Use absolute paths and the venv's interpreter rather than a bare python — the app does not inherit your shell's PATH. Restart the app afterwards.

Anything else

It is a standard stdio MCP server, so any client works. To debug outside one:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

Programs

A program is a JSON file in programs/ describing a multi-day template. sync_program pushes every workout in it, matching on name — existing workouts are updated in place, new ones created. See programs/example.json for a commented template.

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

A block is a repeat group that runs repeat times. A step is either an exercise (exercise + reps, optionally weight_kg and note) or a rest (rest_seconds). A superset is one block holding both exercises with a short rest between and a long rest at the end. Omit weight_kg for bodyweight work. Omit warmup for the default warm-up step, or set it to "" for none.

programs/*.json is gitignored apart from the example, so your own training never lands in a commit.

Things that will bite you

Garmin silently blanks unrecognised exercise names. The upload returns 200, and the exercise shows up nameless on the watch mid-session. This is why search_exercises exists and why every name is resolved against the catalogue before upload. Display names are hyphenated in ways nobody types — "Rope Press-down", "Close-grip Chin-up" — so the search normalises punctuation and understands shorthand like "db", "bb", "ohp", "rdl", "skullcrusher".

The two halves of the API disagree on weight units. The workout-service takes weightValue in kilograms, despite weightUnit carrying "factor": 1000.0. Activity payloads — what you lifted — report grams. Both are handled; don't "fix" either.

Round-trip verification cannot catch a unit error. It compares what Garmin stored against what was sent, and Garmin faithfully stores whatever you send. When grams were being sent, the check passed and Connect displayed "75,000 kg". Eyeball your first upload in Connect.

Update, don't delete-and-recreate. Keeping the workout ID means the watch treats the change as an edit. Recreating makes it drop the old workouts and pull down new ones, which is where stale duplicates come from.

429 and 401 look the same. Garmin rate limits logins per IP, aggressively. When the first login transport is throttled, garminconnect's fallback reports a misleading 401. If you saw 429 just before, it is throttling — wait 30–60 minutes, and don't retry in a loop, which extends the block. To rule out a genuinely wrong password: garmin_login.py --check-env.

Layout

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

Licence

MIT — see LICENSE.

Built on python-garminconnect (MIT) and the MCP Python SDK (MIT).