Garmin MCP App

1# Garmin MCP App
2 
3Connect your Garmin watch to Claude Desktop. Explore interactive charts.
4 
5<p align="center">
6  <img src="https://github.com/user-attachments/assets/62b5ec61-a772-4502-b717-c32c4ea89195" alt="demo" width="600" />
7</p>
8 
9## Install
10 
111. Download the latest `.mcpb` file from [Releases](https://github.com/chenhunghan/garmin-mcp-app/releases)
122. Drag it into Claude Desktop to install
133. Ask Claude anything about your Garmin data — it will prompt you to sign in on first use
14 
15## What you can do
16 
17Ask Claude about your health, training, and fitness — it reads your Garmin data and shows interactive charts right in the conversation.
18 
19- **Review your day** — steps, heart rate, sleep, stress, body battery, and HRV
20- **Analyze your workouts** — activity details, pace splits, HR zones, and training effect
21- **Track your fitness** — training readiness, training load, VO2 Max trends, and race predictions
22- **Plan your training** — create structured workouts, schedule them on your Garmin calendar, or edit existing ones
23 
24What you can visualize
25 
26Plot your activities
27<p align="center">
28  <img width="600" alt="activities" src="https://github.com/user-attachments/assets/c180a8c5-6b8a-4102-aad2-d64fd98e3a85" />
29</p>
30 
31Visualize training readiness
32<p align="center">
33  <img width="600" alt="training readiness" src="https://github.com/user-attachments/assets/42b27fad-f425-4fe7-bd6f-e2816fbe4c12" />
34</p>
35<details>
36<summary>Full list of supported Garmin Connect data</summary>
37 
38| Category     | Data                                                                  |
39| ------------ | --------------------------------------------------------------------- |
40| Daily health | Steps, heart rate, sleep stages, stress, body battery, HRV            |
41| Activities   | Activity list, activity details, per-km/mile splits, HR time-in-zones |
42| Training     | Training readiness, training status & load, VO2 Max, race predictions |
43| Profile      | Age, weight, height, HR zones, lactate threshold                      |
44| Workouts     | List, create, update, delete, and schedule workouts                   |
45 
46</details>
47 
48## Privacy & Security
49 
50**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.
51 
52<details>
53<summary>Learn more</summary>
54 
55- **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**.
56- **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 or OAuth tokens.
57- **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.
58- **You can log out anytime.** Logging out clears all saved tokens from your machine.
59 
60</details>
61 
62---
63 
64<details>
65<summary>Developer / Contributor Guide</summary>
66 
67## Getting Started
68 
69```bash
70git clone https://github.com/chenhunghan/garmin-mcp-app.git
71cd garmin-mcp-app
72npm install
73```
74 
75`npm install` automatically sets up git hooks via [prek](https://github.com/j178/prek):
76 
77- **commit-msg** — enforces [Conventional Commits](https://www.conventionalcommits.org/) via commitlint
78- **pre-push** — runs lint, format check, typecheck, and tests (same as CI)
79 
80### Troubleshooting: `core.hooksPath`
81 
82If `npm install` warns about `core.hooksPath`, prek cannot install git hooks. Fix it by unsetting the local config:
83 
84```bash
85git config --unset-all --local core.hooksPath
86npm run prepare
87```
88 
89## Development
90 
91```bash
92npm run dev        # watch-build server + UI
93npm run dev:ui     # standalone UI dev at localhost:5173
94npm run test:lib   # run garmin-connect tests
95npm run pack       # build + package .mcpb bundle
96```
97 
98`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.
99 
100## Testing in Claude Desktop
101 
102Run `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`:
103 
104```json
105{
106  "mcpServers": {
107    "garmin-mcp": {
108      "command": "node",
109      "args": ["/absolute/path/to/garmin-mcp-app/dist/index.js"]
110    }
111  }
112}
113```
114 
115Restart 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.
116 
117## Architecture
118 
119- **MCP Server** (`src/server.ts`) — Node.js server over stdio, registers tools + UI resource
120- **React UI** (`src/app.tsx`) — Rendered in host's sandboxed iframe, communicates via `postMessage`
121- **garmin-connect** (`packages/garmin-connect/`) — TypeScript client library for Garmin Connect OAuth + API
122 
123## Commit Convention
124 
125Commits must follow the Conventional Commits format:
126 
127```
128type(optional-scope): description
129```
130 
131Allowed types: `feat`, `fix`, `chore`, `docs`, `ci`, `refactor`, `test`
132 
133</details>
134