Skip to main content
Glama
garmin-coach-mcp

garmin-coach-mcp

by MedAlon5

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.

Related MCP server: garmin-mcp

Architecture

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; 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 or the full Hebrew guide for the actual procedure and safety checks.

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:

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

Generate configs (public values only, no secrets):

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:

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

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?

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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables ChatGPT to access and analyze personal Garmin health data including daily steps, heart rate, calories, sleep duration, and body battery levels. Collects data via webhook from Garmin devices and provides health insights through natural language queries.
      1,323 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables reading and analyzing Garmin Connect data—activities, health metrics, FIT files, and challenges—through natural language, for AI assistants like Claude and ChatGPT.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables ChatGPT and compatible AI clients to query read-only Garmin Connect data—including sleep, HRV, heart rate, Body Battery, wellness metrics, and activities—through a hosted OAuth-backed MCP connection using a personal API key.
      2
      15
      1
      MIT