Skip to main content
Glama
garmin-coach-mcp

garmin-coach-mcp

by MedAlon5
README.md
# Garmin ChatGPT Coach — Personal Data, Real Conversations

> Connect **your own Garmin Connect Personal API** to a custom ChatGPT MCP server, so your AI assistant can retrieve real activity, sleep, HRV, heart-rate-zone and daily-summary data rather than relying on screenshots or guesses.

**Status: v0.1.0-beta (community starter / not independently validated on a fresh account).** This repository is adapted from one working personal setup and has been sanitized for reuse. The original setup verified Garmin-backed `tools/list`, OAuth discovery, an authenticated MCP gateway, and tool discovery in ChatGPT. A real Garmin read was observed on the original backend, but a fresh-account end-to-end run of the public package has not been validated. **A clean-room install by a second user, and an authenticated Garmin `tools/call` through the new public template, have not yet been independently verified.** Review the security notes and complete the acceptance checklist before publishing or trusting it with health data.

**Not affiliated with Garmin, Cloudflare, OpenAI, or any employer.** Each user must create **their own** Garmin Personal API key and Cloudflare account. This is for personal use; it is **not** a multi-user hosted Garmin service.

## What can I ask it?

- “Compare my last eight weeks of running: volume, easy pace, average heart rate and long runs.”
- “Summarize my last seven nights of sleep and HRV, showing which dates you actually retrieved.”
- “Review yesterday's run and suggest the next session, explaining the trade-offs.”
- “Build a four-week training proposal toward a faster 10K, using my recent activities and recovery data.”

The AI analyzes the **returned** data; the MCP server supplies read-only raw records. Availability, units and history vary by account/device. A training suggestion is not a medical diagnosis.

## Architecture

```mermaid
flowchart TD
  U[You in ChatGPT] --> C[Custom MCP connection]
  C -->|OAuth 2.1 access token| M[garmin-coach-mcp Worker]
  M -->|AUTH_SERVER Service Binding| A[garmin-coach-oauth Worker]
  A -->|OIDC sign-in + allowlisted email| I[Cloudflare Access]
  A --- K[(Cloudflare KV: OAuth state)]
  M -->|GARMIN_BACKEND Service Binding + separate key| B[garmin-coach Worker]
  B -->|Personal API token + HTTPS| G[Garmin Connect Personal API]
```

**Why three Workers?** The backend owns the private Garmin API key. The authorization Worker handles ChatGPT OAuth and Cloudflare Access login. The MCP resource Worker validates scope and forwards MCP messages to the backend through a **Service Binding**. Avoid ordinary `fetch()` between Workers on the same `workers.dev` zone; that broke discovery in the original implementation.

## The seven tools

| Tool | What it reads | Typical input |
| --- | --- | --- |
| `getActivities` | Paginated activities, newest first | `start`, `limit`, optional `startDate` / `endDate` / `activityType` |
| `getActivity` | One activity and available details | `activityId` |
| `getSleep` | Daily sleep data | `date` (`YYYY-MM-DD`) |
| `getHrv` | Daily heart-rate variability | `date` |
| `getDailySummary` | Daily wellness summary | `date` |
| `getHeartRateZones` | Configured HR zones | none |
| `getProfile` | Garmin profile settings | none |

All tools are **read-only**; they do not update Garmin or send workouts to the watch.

## Before you begin

1. A Garmin Connect account with access to **Garmin Connect Personal API**. Create your personal key from [Garmin Connect settings](https://connect.garmin.com/app/settings/personalApiToken); it is shown only once and has a chosen expiration period. Use it only for **your own account**.
2. A Cloudflare account with Workers, KV and Cloudflare Access/Zero Trust available.
3. A computer with Node.js/npm, Python 3, Git and a terminal.
4. A ChatGPT account/workspace that **actually shows** **Plugins → Add custom MCP server** (feature availability/permissions change; verify *before* setup).
5. Willingness to manage credentials and update the Personal API key when it expires.

Cloudflare and ChatGPT plan eligibility can change. Check their official documentation; do not assume this will be free or supported by every ChatGPT plan.

## Quick start (overview)

**Follow [the full English guide](docs/SETUP_EN.md) or [the full Hebrew guide](docs/SETUP_HE.md) for the actual procedure and safety checks.**

```bash
git clone https://github.com/MedAlon5/garmin-chatgpt-coach.git
cd garmin-chatgpt-coach
npm install
npx wrangler login
npx wrangler kv namespace create OAUTH_KV
```

**Then:** create your Cloudflare Access SaaS OIDC app with callback:

```text
https://garmin-coach-oauth.YOUR_WORKERS_SUBDOMAIN.workers.dev/callback
```

Generate configs (public values only, no secrets):

```bash
python3 scripts/configure.py
python3 scripts/generate_secrets.py
npm run check
```

Deploy in order: Garmin backend → OAuth auth server → MCP gateway. Install secrets via `wrangler secret put`, **not** in tracked files. Connect the final server URL in ChatGPT:

```text
https://garmin-coach-mcp.YOUR_WORKERS_SUBDOMAIN.workers.dev/mcp
```

**Never deploy before `npm test`, `npm run check` and the security review.** The generated files are ignored by Git; secrets must remain in Cloudflare's encrypted secret store or restricted local files.

## Repository layout

```text
workers/
  garmin-backend/src/worker.js        # Garmin API / JSON-RPC MCP tools
  garmin-backend/wrangler.example.jsonc
  integration/src/index.ts           # OAuth authorization server
  integration/src/mcp.ts             # OAuth-protected MCP gateway
  integration/src/config.generated.example.ts
  integration/wrangler.example.jsonc
  integration/mcp.wrangler.example.jsonc
scripts/
  configure.py                      # Account-specific public settings only
  generate_secrets.py               # Two private random keys; prints no values
  smoke_backend.py                  # tools/list test, suppresses credentials
  check_public.py                   # metadata and anonymous-401 checks
AI_SETUP_PROMPT.md                  # Paste into ChatGPT for guided setup
docs/SETUP_EN.md                    # Complete English installation
 docs/SETUP_HE.md                   # Hebrew installation guide
 docs/TROUBLESHOOTING.md            # Common failures and diagnostic workflow
 docs/SECURITY_AND_LIMITATIONS.md    # Threat model and privacy
 docs/VERIFICATION_STATUS.md        # What was actually tested
```

## Important safety notes

- **No credentials or fitness data in Git.** `.local-secrets/`, `.dev.vars`, generated Wrangler configs and account-specific generated TypeScript config are ignored. Always inspect `git status` and `git diff --cached`.
- The OAuth allowlist is a **single verified identity policy** in Cloudflare Access. Never use `Everyone` or `Bypass` for private Garmin data.
- Review the OAuth consent screen's callback destination before approving.
- **Do not turn off authentication** to make tool discovery pass.
- The MCP gateway uses Cloudflare Service Bindings to reach the backend and authorization Worker; the backend does not accept the ChatGPT OAuth token directly.
- Garmin access tokens expire and the personal key can expire or be revoked; refresh the **Garmin key**, not the OAuth configuration, when needed.
- This is a personal experiment, not a validated security product. Get an independent review if you want to expose it to others or publish it as a hosted service.

## Ready to publish?

- [Hebrew publishing checklist and GitHub commands](docs/HOW_TO_PUBLISH_HE.md)
- [LinkedIn post (Hebrew)](LINKEDIN_POST_HE.md)
- [Verification status](docs/VERIFICATION_STATUS.md)
- [Security notes](docs/SECURITY_AND_LIMITATIONS.md)

**Beta statement to preserve when sharing:** The original personal deployment worked, but this generalized template has not yet passed a fresh-account end-to-end test. Do not describe this as a one-click or production-hardened service.

## Reference documentation

- [Garmin Personal API overview](https://developer.garmin.com/gc-developer-program/personal/personal-api/)
- [Garmin Personal API Swagger endpoints](https://developer.garmin.com/gc-developer-program/personal/swagger-docs/)
- [Garmin Personal API FAQ](https://developer.garmin.com/gc-developer-program/personal/personal-faq)
- [Cloudflare Access Generic OIDC application](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/saas-apps/generic-oidc-saas/)
- [Cloudflare workers-oauth-provider](https://github.com/cloudflare/workers-oauth-provider)
- [Cloudflare Worker-to-Worker Service Bindings](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#worker-to-worker-communication)
- [Connecting custom MCP servers in ChatGPT](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt)

## License

MIT. Repository owner should review attribution and licensing terms before publishing. Check upstream notices if copying additional code from example repositories. This repository includes no Garmin/OpenAI/Cloudflare SDK source files or user credentials.