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:

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.

Related MCP server: garth-mcp-server

Tools

Read (9)

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

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

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.