Repository avatar
AI Tools
v0.12.0
active

garmin-mcp-app

io.github.chenhunghan/garmin-mcp-app

Garmin data with interactive charts: daily briefing, training trends, workout planning. Unofficial.

Documentation

Run Coach — Garmin MCP App

Connect your Garmin watch to Claude (desktop, web and mobile) or ChatGPT. Explore interactive charts.

Unofficial. Not affiliated with or endorsed by Garmin. Garmin is a trademark of Garmin Ltd.

demo

Install

Install in ChatGPT Desktop

Claude Desktop

  1. Download the latest .mcpb file from Releases
  2. Drag it into Claude Desktop to install
  3. Ask Claude anything about your Garmin data — it will prompt you to sign in on first use

ChatGPT (desktop app)

Requires Node.js 20+.

  1. In the ChatGPT desktop app, open Settings → Plugins → Add marketplace.
  2. Enter chenhunghan/garmin-mcp-app as the source and select Add marketplace. Leave Git ref and sparse paths empty.
  3. Restart ChatGPT, then open the Plugins Directory and select Run Coach → Coach → Install.

Once the Run Coach marketplace is added, paste this desktop link into your browser's address bar to open the Coach install screen directly.

codex://plugins/install/garmin?marketplace=garmin-mcp

If you already have the Codex CLI, you can add the marketplace and install Coach in one command.

codex plugin marketplace add chenhunghan/garmin-mcp-app && codex plugin add garmin@garmin-mcp

Coach then appears in the sidebar (daily briefing and performance dashboard) and as a Training Week tab in conversations; or just ask "@Coach how am I today?". It runs on your computer, so it works in the desktop app only.

Other MCP clients (Cursor, VS Code, Claude Code, Codex CLI, …)

Requires Node.js 20+. Add the server to your client's MCP config:

{
  "mcpServers": {
    "garmin": { "command": "npx", "args": ["-y", "garmin-mcp-app"] }
  }
}

Or from the command line: claude mcp add garmin -- npx -y garmin-mcp-app (Claude Code), codex mcp add garmin -- npx -y garmin-mcp-app (Codex CLI).

Clients that support MCP Apps (e.g. VS Code) show the interactive charts and the sign-in form. Other clients still get every Garmin tool as data, but can't show the sign-in form: sign in once from an MCP Apps client — the tokens are saved in ~/.garminconnect and shared by every client on your computer.

Claude web and mobile, ChatGPT web: self-host (free)

Run your own Run Coach on Cloudflare's free plan (no credit card) and add it to Claude. It works in Claude on the web, on your computer and on your phone. One Run Coach can serve your household: everyone signs in with their own Garmin account and sees only their own data.

Deploy to Cloudflare

  1. Click Deploy to Cloudflare, sign in or sign up (Cloudflare, and GitHub for your copy of the code).
  2. When it asks for OWNER_PASSPHRASE, choose a password only you know.
  3. Open your Run Coach's address when the deploy finishes (https://run-coach.<you>.workers.dev). The page walks you through adding it to Claude: copy the address, add it under Claude's Customize → Connectors → Add custom connector, then connect with your password and your Garmin sign-in.

Your household: open the Owner page (linked from that page), choose Invite someone and send them the message. They add the same address in their own Claude, choose I'm a household member, enter the invite code and sign in with their own Garmin account. Later they connect with their Garmin sign-in alone. You can remove someone anytime, which deletes their sign-in and disconnects their apps.

Updates install themselves: your copy checks for a new release every Monday and Cloudflare redeploys it. The owner page shows your version. To update right away: GitHub → your copy → Actions → Update Run Coach → Run workflow.

When Garmin's sign-in expires you never need to reconnect: the app shows its sign-in form, and where it can't, the answer carries a one-time sign-in link (valid 10 minutes).

Forgot the password, ChatGPT, limits
  • Forgot the password: Cloudflare dashboard → your Worker → Settings → Variables and Secrets → change OWNER_PASSPHRASE. Apps that are already connected keep working.
  • ChatGPT (web): turn on developer mode, add an app with your Run Coach address and OAuth, then connect the same way. Whether your plan allows custom MCP servers is up to OpenAI.
  • Encryption key: Run Coach generates the key that encrypts Garmin sign-ins on first start. To use your own instead, add a TOKEN_ENCRYPTION_KEY secret (openssl rand -hex 32) before anyone signs in; changing it later means everyone signs in to Garmin again.
  • Updates: the updater replaces every file except wrangler.jsonc (merged, so the IDs Cloudflare wrote into it stay) and .github/. If a release clashes with your wrangler.jsonc, the run fails and changes nothing.
  • Household size: up to 8 members besides you, each with their own encrypted vault.
  • Free plan limits: a long-range performance dashboard loads its metrics over several calls, and the 3D replay's real map (elevation and OpenStreetMap) isn't available yet.
  • Debugging: production stores no logs. npx wrangler tail shows live requests; npm run deploy:dev deploys a separate run-coach-dev Worker with logs on.

What you can do

Ask Claude about your health, training, and fitness — it reads your Garmin data and shows interactive charts right in the conversation.

  • Start your day — a morning briefing: readiness, sleep, HRV, body battery and resting HR against your own baselines, with Claude's suggestions
  • See your trends — compare up to 4 metrics over 4 weeks to a year, and ask Claude what changed
  • Plan your week — Claude designs a week of training from your data, then creates and schedules the workouts on your Garmin calendar
  • Analyze your workouts — per-km splits (even for single-lap runs), HR zones, and training effect
  • Track your fitness — training readiness, training load, VO2 Max, race predictions, and 30+ more Garmin metrics

Your Garmin, coached by Claude

The app frames your data against your own baselines; Claude reads it and suggests what to do. Every view has Ask Claude questions built from your numbers, and Claude knows what you're looking at.

Daily briefing — "How am I today?"

Daily briefing: training readiness 72 with its factors, and tiles for sleep, HRV, body battery, resting HR, stress and steps, each compared with a personal baseline

Performance dashboard — "How has my fitness trended this year?"

Performance dashboard switching from 12 weeks to 1 year: resting HR, HRV with its baseline band, VO2 max and sleep score as small trend charts

Weekly training plan — "Plan my training week" (or the plan-training-week prompt)

Training week: planned workouts paired with completed runs, rest days, and today's long run still to come

Per-km splits — "Show the splits of my last run"

Per-km splits table with pace bars, the fastest kilometre highlighted, HR and cadence per km

Screenshots use the built-in demo mode (npm run dev:ui:demo): a fictional runner, no real person's data. Light and dark themes follow Claude Desktop.

What you can visualize

Plot your activities

activities

Visualize training readiness

training readiness

Full list of supported Garmin Connect data
CategoryData
Daily healthSteps, heart rate, sleep stages, stress, body battery (+ events), HRV, respiration, SpO2, floors, hydration
TrendsResting heart rate, weekly steps, weekly stress, weekly intensity minutes, weigh-ins
ActivitiesList / by date, details, splits, typed splits, HR time-in-zones, chart data, weather, exercise sets, gear
TrainingTraining readiness, training status & load, VO2 Max, race predictions, endurance score, hill score
PerformanceLactate threshold, cycling FTP, HR zones, fitness age, personal records, running tolerance, progress
Devices & gearDevices, primary training device, last used device, gear, goals, training plans, calendar
WorkoutsList, create, update, delete, and schedule workouts

Privacy & Security

No data is stored or collected by this app's author. On your computer (Claude Desktop, ChatGPT desktop, npx), your data flows directly between your machine and the Garmin Connect API. Self-hosted, it flows through your own Cloudflare Worker.

Learn more

On your computer (.mcpb, ChatGPT desktop plugin, npx):

  • Your credentials stay private. You sign in through a secure login form rendered inside Claude Desktop. The login and MFA tools are marked as app-only (visibility: ["app"]), meaning Claude (the LLM) cannot call them and never sees your email, password, or MFA code.
  • Claude doesn't know who you are. The LLM only receives the health/fitness data you ask for (steps, sleep, etc.) — it has no access to your Garmin account credentials, OAuth tokens, or profile (name, email, location).
  • Your password is never sent in plain text. The login form encrypts it with a single-use key before it passes through Claude Desktop, so it can't leak into host logs.
  • Tokens are stored locally. OAuth tokens are saved on your machine at ~/.garminconnect/ with restrictive file permissions (0600). They are never sent anywhere other than the Garmin Connect API.
  • You can log out anytime. Logging out clears all saved tokens from your machine.

Self-hosted (your Cloudflare Worker):

  • Your Worker, your account. Garmin tokens are encrypted (AES-GCM, with a key generated in your Worker or your own TOKEN_ENCRYPTION_KEY) in Durable Objects in your Cloudflare account, one per person. The author never sees them.
  • Only you and the people you invite can connect. You connect with your password (locked for 15 minutes after 5 wrong tries, wrong invite codes included); a household member joins with a one-time invite code and their own Garmin account, which is how they're recognized afterwards. A Garmin account that wasn't invited is refused.
  • Household members trust the owner. Each member's data is kept apart, but it sits encrypted in the owner's Cloudflare account, so whoever controls that account could reach it. The invite page says so.
  • Claude and ChatGPT never see your Garmin password. You type it on your Worker's own sign-in page or in the app's encrypted form; it's used once and never stored.
  • No stored logs. Production keeps Cloudflare's logs off; nothing logs requests, tool calls or results. Your data passes through your Cloudflare account.

Either way: Run Coach uses Garmin Connect's unofficial API, which can change or break, and using it may conflict with Garmin's terms.


Developer / Contributor Guide

Getting Started

git clone https://github.com/chenhunghan/garmin-mcp-app.git
cd garmin-mcp-app
npm install

npm install automatically sets up git hooks via prek:

  • commit-msg — enforces Conventional Commits via commitlint
  • pre-push — runs lint, format check, typecheck, and tests (same as CI)

Troubleshooting: core.hooksPath

If npm install warns about core.hooksPath, prek cannot install git hooks. Fix it by unsetting the local config:

git config --unset-all --local core.hooksPath
npm run prepare

Development

npm run dev        # watch-build server + UI
npm run dev:ui     # standalone UI dev at localhost:5173
npm run test:lib   # run garmin-connect tests
npm run pack       # build + package .mcpb bundle

npm run dev:ui opens http://localhost:5173 with the React UI wired to the real MCP server in-process. You can test login, MFA, and logout against the actual Garmin API without deploying to Claude Desktop.

Testing in Claude Desktop

Run npm run build (one-off) or npm run dev (watch mode for live rebuilds), then add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-mcp-app/dist/index.js"]
    }
  }
}

Restart Claude Desktop. Ask Claude to check your Garmin auth — it will render the app UI in an iframe and run the real login/MFA flow.

Architecture

  • MCP Server (src/server.ts) — Node.js server over stdio, registers tools + UI resource
  • React UI (src/app.tsx) — Rendered in host's sandboxed iframe, communicates via postMessage
  • garmin-connect (packages/garmin-connect/) — TypeScript client library for Garmin Connect OAuth + API
  • Self-hosted Worker (src/worker/) — the same server over Streamable HTTP behind OAuth on Cloudflare Workers (npm run dev:worker, npm run test:worker); design notes in docs/worker-notes.md

Commit Convention

Commits must follow the Conventional Commits format:

type(optional-scope): description

Allowed types: feat, fix, chore, docs, ci, refactor, test

Disclaimer

Run Coach is an independent, open-source project. It is not affiliated with, endorsed by, or sponsored by Garmin Ltd. or its subsidiaries. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries; they are used here only to describe compatibility. The app uses the unofficial Garmin Connect API with your own account.

NPM
garmin-mcp-app
Install Command
npm install garmin-mcp-app