Skip to content

Commit ee88d9b

Browse files
davidmosiahclaude
davidmosiah
and
claude
committed
docs: add auth quickstart walkthrough with real captured CLI output
Showcases the self-contained Node `auth` command (no Python) end-to-end: --help, interactive auth, auth --json (success + missing-creds error), and the post-auth doctor READY report. Output is captured from the actual CLI; the login ran against a mocked Garmin endpoint so no real account was used. Linked from README + docs/quickstart.md, refreshed the stale server.json GARMIN_TOKEN_PATH hint, and bumped to 0.5.1. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 8e1e105 commit ee88d9b

7 files changed

Lines changed: 197 additions & 6 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
# Changelog
22

3-
## Unreleased
3+
## 0.5.1 - 2026-05-29
4+
5+
### Added
6+
7+
- **`examples/auth-quickstart.md`** — end-to-end walkthrough of the self-contained `auth` command with real captured terminal output: `--help`, interactive `auth`, non-interactive `auth --json` (success and missing-credentials error), and the post-auth `doctor` `READY` report. Linked from the README and `docs/quickstart.md` so the no-Python login flow is discoverable.
8+
9+
### Changed
10+
11+
- `server.json` `GARMIN_TOKEN_PATH` description now points at the self-contained `auth` (no Python) instead of the legacy `auth --install-helper`.
12+
13+
## 0.5.0 - 2026-05-28
414

515
### Added
616

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,8 @@ npx -y garmin-mcp-unofficial setup --auth
7171

7272
`auth` runs a self-contained Node login and prompts locally for Garmin email, password and MFA when needed. The MCP **does not store your Garmin password** — only Garmin Connect tokens, saved at `~/.garmin-mcp/garmin_tokens.json` with user-only permissions.
7373

74+
> 📺 **Want to see exactly what each command prints?** The [auth quickstart walkthrough](examples/auth-quickstart.md) shows real `--help`, `auth`, `auth --json` and `doctor` output for the full first-call journey.
75+
7476
Prefer the old Python flow? `auth --use-python` (or `auth --install-helper` to install the `garminconnect` package, with an isolated virtualenv fallback under `~/.garmin-mcp/venv`) still works.
7577

7678
Then add this to your MCP client config:

‎docs/quickstart.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ npx -y garmin-mcp-unofficial auth
2222

2323
The built-in login prompts locally for Garmin email, password and MFA when needed — no Python required. The MCP does not store your Garmin password.
2424

25+
See the [auth quickstart walkthrough](../examples/auth-quickstart.md) for the real terminal output of `auth`, `auth --json` and `doctor`.
26+
2527
Prefer the legacy Python helper? Use `auth --use-python`, or `auth --install-helper` to install the `garminconnect` package (it falls back to an isolated virtualenv under `~/.garmin-mcp/venv` if Homebrew or PEP 668 blocks the install).
2628

2729
## 3. Check readiness

‎examples/auth-quickstart.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Auth quickstart — self-contained Node login (no Python)
2+
3+
As of `garmin-mcp-unofficial` 0.5.0, `auth` runs a **pure-Node** Garmin Connect
4+
login: SSO sign-in, MFA, and the OAuth1 → OAuth2 ticket exchange are implemented
5+
in the package itself. **No Python and no `garminconnect` package are required.**
6+
7+
Your Garmin **password is never stored** — only short-lived Garmin Connect
8+
tokens are written to `~/.garmin-mcp/garmin_tokens.json` with `0600`
9+
(user-only) permissions.
10+
11+
This page shows the real command output for the whole first-call journey. Every
12+
block below is captured from the actual CLI (the login here ran against a mocked
13+
Garmin endpoint so no real account was used; the success/doctor output is the
14+
genuine code path).
15+
16+
## The three-command path
17+
18+
```bash
19+
npx -y garmin-mcp-unofficial setup # writes local MCP config (no password)
20+
npx -y garmin-mcp-unofficial auth # built-in Node login, prompts locally
21+
npx -y garmin-mcp-unofficial doctor # confirms you're ready
22+
```
23+
24+
## What `--help` shows
25+
26+
```text
27+
$ garmin-mcp-server --help
28+
Garmin MCP Server
29+
30+
Usage:
31+
garmin-mcp-server Start MCP stdio server
32+
garmin-mcp-server --http Start local HTTP MCP server
33+
garmin-mcp-server setup Guided setup, local config, and MCP client config
34+
garmin-mcp-server setup --auth Setup, then immediately start local Garmin auth
35+
garmin-mcp-server doctor Check setup and next steps
36+
garmin-mcp-server doctor --json Print setup status as JSON
37+
garmin-mcp-server doctor --client hermes
38+
garmin-mcp-server auth Log in to Garmin locally (no Python needed) and save ~/.garmin-mcp/garmin_tokens.json
39+
garmin-mcp-server auth --json Non-interactive login using GARMIN_EMAIL / GARMIN_PASSWORD (+ GARMIN_MFA_CODE)
40+
garmin-mcp-server auth --use-python
41+
Use the legacy Python garminconnect helper instead of the built-in login
42+
garmin-mcp-server auth --install-helper
43+
Alias of --use-python: install the Python garminconnect helper if missing
44+
garmin-mcp-server onboarding Print the shared Delx wellness onboarding flow (11 questions)
45+
garmin-mcp-server onboarding --pt-BR
46+
Print the onboarding flow in pt-BR
47+
48+
Optional env/config:
49+
GARMIN_TOKEN_PATH=~/.garmin-mcp/garmin_tokens.json
50+
GARMIN_PRIVACY_MODE=summary|structured|raw
51+
GARMIN_CACHE=sqlite
52+
```
53+
54+
## Interactive login
55+
56+
`auth` with no flags prompts in your terminal. The password input is masked, and
57+
MFA is requested only when your account requires it:
58+
59+
```text
60+
$ garmin-mcp-server auth
61+
Garmin email: you@example.com
62+
Garmin password: ************
63+
Garmin MFA code: 123456 # only asked if your account has MFA enabled
64+
65+
✓ Garmin connected
66+
67+
Token file: /home/you/.garmin-mcp/garmin_tokens.json
68+
Permissions: 600
69+
70+
→ Next: Run `garmin-mcp-server doctor`, then start your MCP client.
71+
```
72+
73+
## Non-interactive login (CI / agents): `auth --json`
74+
75+
For automation, pass credentials via environment variables. Output is a single
76+
JSON object you can parse:
77+
78+
```bash
79+
GARMIN_EMAIL=you@example.com \
80+
GARMIN_PASSWORD=app-password \
81+
GARMIN_MFA_CODE=123456 \
82+
garmin-mcp-server auth --json
83+
```
84+
85+
```json
86+
{
87+
"ok": true,
88+
"token_path": "/home/you/.garmin-mcp/garmin_tokens.json",
89+
"permissions": "600",
90+
"has_di_token": true,
91+
"has_refresh_token": true,
92+
"next_step": "Run `garmin-mcp-server doctor`, then start your MCP client."
93+
}
94+
```
95+
96+
If credentials are missing, `auth --json` exits `1` with a clear, actionable
97+
error (real output):
98+
99+
```text
100+
$ garmin-mcp-server auth --json
101+
{
102+
"ok": false,
103+
"error": "Set GARMIN_EMAIL and GARMIN_PASSWORD (and GARMIN_MFA_CODE if prompted) to run `auth --json`, or run `garmin-mcp-server auth` interactively."
104+
}
105+
```
106+
107+
## Confirm readiness with `doctor`
108+
109+
After a successful `auth`, `doctor` reports `READY` and verifies token
110+
permissions are locked down (real output):
111+
112+
```text
113+
$ garmin-mcp-server doctor
114+
Garmin MCP · Doctor
115+
Status: READY ✓
116+
117+
Checks
118+
✓ Node.js >=20
119+
· Local config
120+
✓ Token file
121+
✓ Token permissions
122+
✓ DI token
123+
✓ DI refresh token
124+
· Privacy mode
125+
· Cache
126+
127+
Next steps
128+
1. Ready. Add this MCP server to your agent and start with garmin_daily_summary.
129+
```
130+
131+
`doctor --json` for programmatic checks:
132+
133+
```json
134+
{
135+
"ok": true,
136+
"node": { "version": "22.22.2", "supported": true },
137+
"automatic_auth_supported": true,
138+
"privacy_mode": "structured",
139+
"token": {
140+
"exists": true,
141+
"readable": true,
142+
"secure_permissions": true,
143+
"expired": false,
144+
"has_refresh_token": true,
145+
"has_di_token": true
146+
},
147+
"cache": { "enabled": false },
148+
"next_steps": [
149+
"Ready. Add this MCP server to your agent and start with garmin_daily_summary."
150+
]
151+
}
152+
```
153+
154+
## First agent call
155+
156+
Once `doctor` is `READY`, point your MCP client at the server and ask:
157+
158+
```text
159+
Call garmin_connection_status. If ready, call garmin_daily_summary with
160+
response_format=json and give me today's main recovery/training signal with
161+
3 practical actions. Do not provide medical diagnosis.
162+
```
163+
164+
## Prefer the legacy Python helper?
165+
166+
The old flow still works and is fully opt-in:
167+
168+
```bash
169+
garmin-mcp-server auth --use-python # use an existing garminconnect install
170+
garmin-mcp-server auth --install-helper # install garminconnect (falls back to ~/.garmin-mcp/venv)
171+
```
172+
173+
---
174+
175+
This is an **unofficial** project that uses personal Garmin Connect token mode —
176+
not the official Garmin Health API. Garmin can change private auth at any time;
177+
treat failures as integration drift, not user error.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "garmin-mcp-unofficial",
3-
"version": "0.5.0",
3+
"version": "0.5.1",
44
"description": "Unofficial local-first Garmin MCP server for AI health, sleep and activity agents.",
55
"type": "module",
66
"bin": {

‎server.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,19 @@
66
"url": "https://github.com/davidmosiah/garmin-mcp",
77
"source": "github"
88
},
9-
"version": "0.5.0",
9+
"version": "0.5.1",
1010
"packages": [
1111
{
1212
"registryType": "npm",
1313
"identifier": "garmin-mcp-unofficial",
14-
"version": "0.5.0",
14+
"version": "0.5.1",
1515
"transport": {
1616
"type": "stdio"
1717
},
1818
"environmentVariables": [
1919
{
2020
"name": "GARMIN_TOKEN_PATH",
21-
"description": "Optional local path for Garmin Connect tokens. Defaults to ~/.garmin-mcp/garmin_tokens.json. Create it with garmin-mcp-server auth --install-helper.",
21+
"description": "Optional local path for Garmin Connect tokens. Defaults to ~/.garmin-mcp/garmin_tokens.json. Create it with garmin-mcp-server auth (self-contained Node login, no Python).",
2222
"isRequired": false,
2323
"format": "string",
2424
"isSecret": false

‎src/constants.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
export const SERVER_NAME = "garmin-mcp-server";
2-
export const SERVER_VERSION = "0.5.0";
2+
export const SERVER_VERSION = "0.5.1";
33
export const NPM_PACKAGE_NAME = "garmin-mcp-unofficial";
44
export const PINNED_NPM_PACKAGE = `${NPM_PACKAGE_NAME}@${SERVER_VERSION}`;
55

0 commit comments

Comments
 (0)