garmin-coach-mcp

An MCP server that lets Claude read and answer questions about your Garmin Connect data — recent activities, per-set strength history, sleep and recovery, and simple trends — and optionally build workouts back onto your watch.

It runs two ways from the same code:

Mode	Transport	Where	Use it for
Local	stdio	Your PC, launched on demand by Claude Code	Day-to-day work at your desk
Hosted	streamable HTTP	Azure Container Apps	Asking from your phone, PC switched off

Local mode is the default. Nothing listens on a socket and no secret is involved — the server is a subprocess Claude Code owns. Hosted mode is opt-in via GARMIN_COACH_TRANSPORT=http and refuses to start without a shared secret.

Note: This uses python-garminconnect, which talks to Garmin's unofficial API. It works well for personal use but isn't sanctioned by Garmin and can break if Garmin changes their backend.

Layout

├── src/garmin_coach_mcp/     the server
│   ├── server.py             tool definitions + transport selection
│   ├── config.py             environment-driven settings
│   ├── http_app.py           hosted transport + shared-secret gate
│   ├── garmin_client.py      cached, token-authenticated Garmin client
│   ├── analysis.py           strength-history and trend computations
│   ├── strength_workout.py   Garmin workout payload builder
│   └── login.py              one-time interactive Garmin login
├── infra/                    Bicep for the hosted deployment
├── tests/                    secret-gate and config tests
├── docs/
│   ├── local-setup.md        run it on your PC
│   ├── remote-setup.md       deploy it to Azure with Microsoft sign-in
│   └── architecture.md       design decisions and what was learned deploying it
├── scripts/check_secrets.py  pre-commit credential scanner
└── .env.example              every setting, documented

Your own data stays out of the repo. .gitignore excludes .azure/ (which holds live secrets), the Garmin token, and docs/body-composition/ + training/ if you keep personal records alongside the code. Run python scripts/check_secrets.py before publishing, or enable it as a hook with git config core.hooksPath .githooks.

Tools

Read (9)

Tool	What it answers
garmin_status	Is the connection working? Whose account?
list_activities(limit, activity_type)	"Show my last N workouts"
get_activity(activity_id)	Detailed metrics for one activity
get_exercise_sets(activity_id)	Per-set exercise / reps / weight / est. 1RM
get_strength_history(exercise_name, weeks)	"Is my squat going up?"
get_recovery(date)	Sleep + daily stats + training readiness
get_trends(metric, weeks, sample_days)	Resting HR, steps, stress over time
suggest_next_weight(exercise_name, ...)	Progressive-overload recommendation
list_workouts(limit)	Saved workouts (name + id)

Write (3) — set GARMIN_COACH_READONLY=1 to drop these from the manifest entirely.

Tool	What it does
create_strength_workout(name, exercises, schedule_date)	Build a strength workout on Garmin (experimental)
schedule_workout(workout_id, date)	Put an existing workout on your calendar
delete_workout(workout_id)	Undo / remove a workout

Strength answers only have data if you log Strength activities with weights on your watch. create_strength_workout uses Garmin's unofficial workout schema — check the result in the Garmin Connect app and delete_workout if it's wrong.

Quick start (local)

cd C:\Projects\garmin-coach-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\garmin-coach-login.exe          # one time, caches a token
claude mcp add garmin-coach -s user -- C:\Projects\garmin-coach-mcp\.venv\Scripts\python.exe -m garmin_coach_mcp.server

Full walkthrough: docs/local-setup.md.

Quick start (hosted)

azd env new garmin-coach --subscription <id> --location westus2
azd env set MCP_SECRET (python -c "import secrets; print(secrets.token_urlsafe(32))")
azd up

Then seed the Garmin token onto the file share and add the connector. Full walkthrough: docs/remote-setup.md.

Configuration

Variable	Default	Meaning
GARMIN_COACH_TRANSPORT	stdio	stdio or http
GARMIN_COACH_SECRET	—	Required for http. Minimum 32 chars
GARMIN_COACH_HOST	0.0.0.0	HTTP bind address
GARMIN_COACH_PORT	8080	HTTP port
GARMIN_COACH_READONLY	off	Hide the three write tools
GARMINTOKENS	~/.garminconnect	Where the Garmin OAuth token lives
GARMIN_COACH_ALLOWED_HOSTS	localhost only	Host headers the MCP SDK will accept
GARMIN_COACH_TENANT_ID	—	Entra tenant issuing tokens
GARMIN_COACH_CLIENT_ID	—	Entra app ID; required audience on tokens
GARMIN_COACH_ALLOWED_OIDS	—	Object IDs permitted to call the server
GARMIN_COACH_PUBLIC_URL	—	This server's public URL, for RFC 9728 metadata

The last four are all-or-nothing: set together they enable Microsoft sign-in; set partially the server refuses to start rather than advertising an auth flow that can't issue usable tokens.

Tests

.\.venv\Scripts\python.exe tests\test_http_gate.py

These cover the shared-secret gate — the only thing between the public internet and your Garmin account when hosted — plus the configuration guards that stop the server starting in an unsafe combination.

Troubleshooting

• garmin_not_authenticated — run garmin-coach-login (token missing or expired). Hosted: re-run it locally, then re-upload the token to the file share.
• Server not connecting locally — confirm the venv path in claude mcp list; the command must point at .venv\Scripts\python.exe.
• No strength data — the workout must be logged as a Strength activity with weights on the watch for get_exercise_sets / get_strength_history to return anything.
• Hosted returns 404 for everything — the secret in the URL doesn't match GARMIN_COACH_SECRET. A wrong secret is deliberately indistinguishable from a wrong path.