Run Coach

io.github.chenhunghanv0.9.0Updated Oct 8, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsLocation & LifestyleProductivity & Workflow

Overview

AI-generated overview

Lets an assistant read your Garmin Connect health and training data, show interactive charts, and create or schedule workouts.

What it does
Run Coach connects an assistant to your own Garmin Connect account. It exposes daily health and activity data (steps, heart rate, sleep stages, stress, body battery, HRV, SpO2), training metrics (training readiness, load, VO2 Max, race predictions, lactate threshold, HR zones), and workout tools that can list, create, update, delete, and schedule workouts on your Garmin calendar. It also renders interactive charts and a sign-in form in clients that support MCP Apps, and offers prompts such as a daily briefing and a weekly training plan.
When to use it
Useful if you already track training and health with a Garmin device and want an assistant to summarize readiness and sleep, compare trends over weeks or months, analyze per-kilometer splits and heart-rate zones, or draft and schedule a training week from your own data.
Requirements
Runs locally over stdio, either as an .mcpb bundle dragged into Claude Desktop or via npx garmin-mcp-app. Node.js 20+ is required for the ChatGPT desktop app and other MCP clients. Desktop only; no web version. A Garmin Connect account is needed, and you sign in through the app's login form, including MFA. OAuth tokens are saved locally under ~/.garminconnect.
Before you install
It asks for your Garmin Connect email, password, and MFA code through an app-only login form; the assistant is not meant to see them, and the password is encrypted with a single-use key before passing through the host. OAuth tokens are stored on your machine at ~/.garminconnect with 0600 permissions. Workout tools can create, update, delete, and schedule workouts on your Garmin calendar, so review changes before confirming. It uses the unofficial Garmin Connect API and is not affiliated with…

Installation

In SourceWeft

  1. Open Run Coach in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Run Coach — Garmin MCP App

Connect your Garmin watch to Claude Desktop or ChatGPT. Explore interactive charts.

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

[demo]

Install

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. Source: chenhunghan/garmin-mcp-app (leave Git ref and sparse paths empty) → Add marketplace
  3. Restart the app, open the Plugins Directory, choose the Run Coach marketplace and install Coach

Or with the Codex CLI: codex plugin marketplace add chenhunghan/garmin-mcp-app then 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:

json
{  "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.

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. Your data flows directly between your machine and the Garmin Connect API — there is no intermediate server.

Learn more
  • 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.
Developer / Contributor Guide

Getting Started

bash
git clone https://github.com/chenhunghan/garmin-mcp-app.gitcd garmin-mcp-appnpm 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:

bash
git config --unset-all --local core.hooksPathnpm run prepare

Development

bash
npm run dev        # watch-build server + UInpm run dev:ui     # standalone UI dev at localhost:5173npm run test:lib   # run garmin-connect testsnpm 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:

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

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.

Source: README.md at commit dea4b26

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.9.0LatestOct 8, 2026