Garmin MCP for Claude

Your own Garmin Connect data in Claude. This is a personal, self-hosted remote MCP server on Cloudflare Workers (free plan) that you add to claude.ai as a custom connector.

It covers:

• Recovery: sleep, HRV, resting heart rate, Body Battery and stress.

• Training: activities, laps, VO2 max, Fitness Age and training load.

• Computed metrics: readiness, ACWR and recovery after hard sessions.

Typical use: ask Claude "How did I sleep, and how hard should I train today?", or schedule a daily morning brief.

• Single user: you deploy your own instance with your own Garmin key, and nobody else can use it.

• Uses the official Garmin Connect Personal API. Personal, non-commercial use only.

• Not affiliated with or endorsed by Garmin or Anthropic.

What you need

• A Garmin Connect account and a Personal API key. Create the key at https://connect.garmin.com/app/settings/personalApiToken. It is shown only once; you choose an expiry of 30, 90 or 180 days or 1 year.

• A free Cloudflare account.

• Node.js 22+ and npm.

• A Claude plan that supports custom connectors.

Related MCP server: Garmin MCP Worker

Setup (about 10 minutes)

git clone https://github.com/<you>/garmin-mcp.git
cd garmin-mcp
npm install
cp .env.example .env           # then put your key in .env: GARMIN_API_KEY=...
npx wrangler login             # log in to YOUR Cloudflare account
npm run setup                  # creates everything and deploys (see below)
node scripts/backfill.mjs      # loads all your Garmin history into the database

npm run setup (scripts/setup-instance.mjs) is safe to run again; steps that are done are skipped. It:

1. pins wrangler.jsonc to your Cloudflare account id, so it can never deploy into another account;

2. creates the KV namespaces and the D1 database and writes their ids into wrangler.jsonc;

3. applies the D1 migrations;

4. uploads your Garmin key as a Worker secret, and creates a login passphrase in CONNECTOR_LOGIN.txt (local only, gitignored);

5. registers a workers.dev subdomain if your account has none, sets the connector URL, and deploys.

At the end it prints your connector URL, e.g. https://garmin-mcp.<subdomain>.workers.dev/mcp.

Add it to Claude:

1. Go to Settings → Connectors → Add custom connector.

2. Paste the URL and leave the OAuth Client ID and Secret empty.

3. Click Connect and enter the passphrase from CONNECTOR_LOGIN.txt.

After npm run setup, wrangler.jsonc contains your account and resource ids. They are not secrets, but if you publish a fork, keep your setup-modified wrangler.jsonc out of it.

Tools

Garmin data vs. computed metrics

Every result starts with a provenance block:

• garmin_provided: fields supplied by Garmin, passed through unchanged except for unit conversion.

• computed_by_connector: fields this connector calculates itself.

The server's MCP instructions tell Claude to say which is which, and never to present a computed metric (such as readiness) as a Garmin feature. Tool descriptions are labelled [Garmin data] or [Connector's own calculation; not Garmin …].

Not available from the Garmin Personal API

• Training Readiness and Training Status. get_readiness and get_training_load are this connector's own metrics instead, and they will differ from the watch.

• Race predictions.

• Lactate threshold.

• Workout or course push: the API is read-only.

• VO2 max as an API field. It is read from the FIT file instead; see Formulas.

See ENDPOINTS.md for the endpoints used and their response shapes.

How it works

claude.ai ──OAuth 2.1 (DCR + PKCE)──▶ Cloudflare Worker
                                      ├─ workers-oauth-provider: /.well-known/*, /register, /token, /authorize (passphrase login)
                                      ├─ /mcp (token required) → MCP server (Streamable HTTP)
                                      │     ├─ recovery service   D1 first (completed days), Garmin API for the rest
                                      │     └─ activity service   activities, FIT laps, load / readiness / recovery
                                      └─ cron 05:30 local → nightly sync of the last 3 days into D1
Garmin client → personal.connectapi.garmin.com (token cached in KV; 401 → refresh + retry; 429 → backoff)
FIT parsing → @garmin/fitsdk (unneeded messages are stripped first to stay within the free plan's CPU limit)

Security

• Protected endpoint: only /mcp serves data, and it requires a valid OAuth access token.

• Login: a passphrase checked against a PBKDF2 hash. The login form has a one-time CSRF state bound to a __Host- cookie.

• Brute-force protection: 5 failed logins per IP per 15 minutes, and 20 per hour in total.

• Secrets: they live only in your local .env and in Worker secrets. The scripts pipe them in and never print them.

• Logs: they contain counts only, never health data.

Formulas

• Training load / ACWR:

  • Daily load = the sum of Garmin's per-activity activityTrainingLoad.

  • Acute load = the 7-day mean; chronic load = the 28-day mean; ACWR = acute / chronic.

  • Status: < 0.8 detraining, < 1.0 maintaining, ≤ 1.3 productive, above that overreaching_risk. It is insufficient_data with less than 28 days of history or very low load.

• Readiness (0–100):

  component	weight	score
  HRV	30%	70 + 15·z vs your 60-day baseline
  Resting HR	20%	70 + 15·z, inverted (lower is better)
  Sleep score	20%	Garmin sleep score
  Sleep duration	15%	100 · min(1, h/8)
  Load	15%	ACWR through yesterday: ≤ 1.0 → 100, 1.3 → 70, 1.5 → 30, ≥ 2.0 → 0

  • Missing parts are dropped and the weights renormalized. The same inputs always give the same score.

• Recovery after a hard day:

  • Bands: HRV uses Garmin's "balanced" range; resting HR uses your 60-day mean ± 1 sd.

  • Counting: only the first night after the activity decides whether a value left its band (day 2 if day 1 has no data). If it did, the count runs to the first night back in band.

• Body Battery at wake: the 15-minute reading closest to the end of sleep. Garmin's Body Battery report covers roughly the last 4 months.

• VO2 max:

  • Source: the watch stores its estimate in each outdoor activity's FIT file, in the undocumented message 140, field 7: VO2 max = raw × 3.5 / 65536.

  • Validation: the format is community-documented and was validated against a watch, which shows the value rounded to an integer.

  • Treadmill: treadmill activities don't update it, so they are stored as null.

Configuration

• Time zone: dates are interpreted in Europe/Oslo. To change it:

  • set TIMEZONE in src/dates.ts;

  • adjust the two UTC crons in wrangler.jsonc so that one of them hits 05:30 local time in summer and winter;

  • adjust the hour check in isOsloSyncHour (src/sync/sync.ts).

• Worker name / URL: change name in wrangler.jsonc before running npm run setup.

• Strength training: strength sessions are listed and count towards training load, but set, rep and weight details are not parsed.

Maintenance

Tests: npm test runs the unit and integration tests. They use mocked Garmin responses, FIT fixtures and D1 on node:sqlite. npm run type-check checks the types.

Contributing

Issues and pull requests are welcome. Please:

• run npm test and npm run type-check;

• never commit .env, CONNECTOR_LOGIN.txt or real health data (test fixtures must be synthetic).

License

MIT. Use of the Garmin Connect Personal API is subject to Garmin's own terms (personal, non-commercial use).