Skip to content
Back to search

garmin_mcp

MCP server to access Garmin data

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/taxuspt--garmin-mcp/badge.svg)](/listings/taxuspt--garmin-mcp)

HTML

<a href="/listings/taxuspt--garmin-mcp"><img src="/api/listings/taxuspt--garmin-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Start for MCP Clients

The easiest way to use this MCP server with Claude Desktop, [Codex](https://openai.com/codex/), or another MCP client is to authenticate once before adding the server to your configuration.

Prerequisites

- Python 3.12+ - Garmin Connect account - MFA may be required if enabled on your account

Step 1: Pre-authenticate (One-time)

Before adding the server to your MCP client, authenticate once in your terminal:


# Install and run authentication tool
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth

# You'll be prompted for:
# - Email (or set GARMIN_EMAIL env var)
# - Password (or set GARMIN_PASSWORD env var)
# - MFA code (if enabled on your account)

# OAuth tokens will be saved to ~/.garminconnect

You can verify your credentials at any time with

uv run garmin-mcp-auth --verify

**Note:** You can also set credentials via environment variables:

GARMIN_EMAIL=your@email.com GARMIN_PASSWORD=secret garmin-mcp-auth

If you don't have MFA enabled you can also skip `garmin-mcp-auth` and pass `GARMIN_EMAIL` and `GARMIN_PASSWORD` as env variables directly to your MCP client, if supported. For better security, prefer the pre-authentication flow above and keep credentials out of MCP client configuration.

Step 2: Configure Claude Desktop

Add to your Claude Desktop MCP settings **WITHOUT** credentials:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ]
    }
  }
}

**Important:** No `GARMIN_EMAIL` or `GARMIN_PASSWORD` needed in config! The server uses your saved tokens.

Step 3: Restart your MCP client

Your Garmin data is now available to your MCP client.

For Codex and other clients, see the examples below.

---

Using more than one Garmin account

A single server process is bound to one Garmin account. To use several accounts at once, run **one server instance per account**, each with its own token directory, selected with the `GARMINTOKENS` environment variable.

`GARMINTOKENS` defaults to `~/.garminconnect`. Point it somewhere else and the server reads and writes tokens there instead, leaving the default store untouched.

Step 1: Authenticate each account into its own directory

garmin-mcp-auth --token-path ~/.garminconnect-alice
garmin-mcp-auth --token-path ~/.garminconnect-bob

`--token-path` also accepts `$GARMINTOKENS`, so `GARMINTOKENS=~/.garminconnect-alice garmin-mcp-auth` is equivalent.

Step 2: Declare one server per account

{
  "mcpServers": {
    "garmin-alice": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
      "env": {
        "GARMINTOKENS": "${HOME}/.garminconnect-alice"
      }
    },
    "garmin-bob": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
      "env": {
        "GARMINTOKENS": "${HOME}/.garminconnect-bob"
      }
    }
  }
}

Each server logs the directory it authenticates from on startup, so you can confirm the wiring:

Trying to login to Garmin Connect using token data from directory '/home/you/.garminconnect-alice'...

Notes

- **No silent fallback.** If `GARMINTOKENS` points at a directory with no valid tokens, startup fails with `GarminConnectAuthenticationError` rather than falling back to the default store. A misconfigured second server cannot silently reuse the first account's session. - **`${HOME}` is expanded** even when an MCP client passes it through unresolved, and `~` works on Windows via `USERPROFILE`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,226 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/taxuspt-garmin-mcp-badge.png)](https://mseep.ai/app/taxuspt-garmin-mcp)
  2. # Garmin MCP Server
  3. This Model Context Protocol (MCP) server connects to Garmin Connect and exposes your fitness and health data to Claude and other MCP-compatible clients.
  4. Garmin's API is accessed via the awesome [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) library.
  5. ## Features
  6. - List recent activities with pagination support
  7. - Get detailed activity information
  8. - Edit activities: name, type, description/notes, event type, perceived effort (RPE), feel, and strength exercise sets
  9. - Access health metrics (steps, heart rate, sleep, stress, respiration)
  10. - View body composition data
  11. - Track training status and readiness
  12. - Access cycling FTP and lactate threshold metrics
  13. - Manage gear and equipment, including free-text notes returned by `get_gear`
  14. - Access workouts and training plans
  15. - Inspect detailed workout step structures, including repeat groups and swim pace targets
  16. - Weekly health aggregates (steps, stress, intensity minutes)
  17. - Advanced cycling analytics: power zones, FIT file analysis, DI2 electronic shift intelligence
  18. - Training load trend (CTL/ATL/TSB), HRV trend, VO2 max trend, respiration rate trend
  19. - Power Duration Curve, climb detection with VAM, cardiac drift (aerobic decoupling), W/kg calculations
  20. ### Tool Coverage
  21. This MCP server implements **110+ tools** covering ~90% of the [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) library (v0.3.2):
  22. - ✅ Activity Management (21 tools) - includes write tools for type, description, event type, perceived effort, feel, and exercise sets
  23. - ✅ Health & Wellness (34 tools) - includes custom lightweight summary tools
  24. - ✅ Training & Performance (13 tools) - includes CTL/ATL/TSB, HRV, VO2 max, and respiration trends
  25. - ✅ Workouts (8 tools)
  26. - ✅ Devices (8 tools) - includes sending a workout to a device
  27. - ✅ Gear Management (5 tools)
  28. - ✅ Weight Tracking (5 tools)
  29. - ✅ Challenges & Badges (10 tools)
  30. - ✅ Nutrition (9 tools) - food logs, meals, custom foods, food logging, and multi-day intake summaries
  31. - ✅ Women's Health (3 tools)
  32. - ✅ User Profile (3 tools)
  33. - ✅ High-Level Workout Builders (4 tools) - create and schedule workouts without writing JSON
  34. - ✅ Courses (5 tools) - list / get details / upload GPX as course / download GPX / delete course
  35. - ✅ Activity Analysis (2 tools) - FIT file parsing, Power Duration Curve; requires power meter and/or Di2
  36. - ✅ Activity File Downloads (2 tools) - download activity files in FIT, GPX, TCX, or CSV format
  37. > **Note:** Activity Analysis tools require a compatible power meter (e.g., Garmin Rally, Favero Assioma, PowerTap P1) and/or Shimano Di2 / SRAM eTap electronic shifting. The `fitparse` dependency is installed automatically.
  38. ### Gear Notes
  39. Each item in the `gear` array returned by `get_gear` includes a `notes` field
  40. containing the free-text Notes value shown in Garmin Connect. Gear without a
  41. Notes value returns `null`; all existing gear fields remain unchanged.
  42. ### Activity File Downloads
  43. Two tools let you download a raw activity file to disk:
  44. - **`download_activity_file(activity_id, format="fit", output_dir=None)`** — downloads the activity and saves it to the configured directory. `format` accepts `fit` (default), `gpx`, `tcx`, or `csv`.
  45. - **`set_fit_download_dir(path)`** — sets and persists the default download directory (written to the config file).
  46. **Where files are saved (precedence):**
  47. 1. `output_dir` argument — one-off override, not persisted.
  48. 2. `GARMIN_FIT_DOWNLOAD_DIR` environment variable.
  49. 3. Persisted config set via `set_fit_download_dir`.
  50. **First-run behavior:** if no directory is configured, `download_activity_file` returns `status: "needs_setup"`. The assistant will ask where you want to save files (suggesting the current directory as default), call `set_fit_download_dir` to persist your choice, and then retry the download automatically.
  51. ### Strength Exercise Sets
  52. `set_activity_exercise_sets(activity_id, sets)` writes structured sets onto a recorded
  53. strength activity, the same per-set grid the Garmin Connect "Edit sets" screen saves, so
  54. they appear in Garmin's exercise history and volume charts. It **replaces every existing
  55. set**, including watch-detected ones; read them first with `get_activity_exercise_sets`
  56. if you want to keep any.
  57. Each set takes a `category` and optional `exercise_name` using Garmin's keys from
  58. [`Exercises.json`](https://connect.garmin.com/web-data/exercises/Exercises.json), plus
  59. optional `reps`, `weight_kg` or `weight_lb` (omit for bodyweight), `duration_seconds` and
  60. `rest_seconds`. Garmin rejects unknown keys and leaves the activity unchanged.
  61. If the watch recorded the right sets but misidentified the exercises, pass
  62. `keep_timing: true`: the recorded start times, durations and rest periods are kept and only
  63. the exercise, reps and weight are replaced, in order. The number of sets must match the
  64. activity's recorded active sets.
  65. ```json
  66. {
  67. "activity_id": 12345678901,
  68. "sets": [
  69. {"category": "DEADLIFT", "exercise_name": "BARBELL_DEADLIFT", "reps": 5, "weight_kg": 150, "rest_seconds": 180},
  70. {"category": "PULL_UP", "reps": 8}
  71. ]
  72. }
  73. ```
  74. ### Intentionally Skipped Endpoints
  75. Some endpoints are not implemented due to performance or complexity considerations:
  76. **High Data Volume:**
  77. - `get_activity_details()` - Returns large GPS tracks and chart data (50KB-500KB). Use `get_activity()` for summaries instead.
  78. **Specialized Workout Formats:**
  79. - `upload_running_workout()`, `upload_cycling_workout()`, `upload_swimming_workout()` - Sport-specific workout uploads. Use `upload_workout()` for general workouts.
  80. **Maintenance & Destructive Operations:**
  81. - `delete_blood_pressure()` - Destructive operations require careful consideration.
  82. - `delete_activity()` is implemented with a confirmation gate: call once to
  83. preview, then again with `confirm=true` to delete. Deletions are logged to
  84. stderr. There is no undo.
  85. - Internal/Auth methods: `login()`, `resume_login()`, `connectapi()`, `download()` - Handled automatically by the library.
  86. If you need any of these endpoints, please [open an issue](https://github.com/Taxuspt/garmin_mcp/issues).
  87. ## Tool Filtering
  88. This server registers 155 tools by default, which is a lot of context for an
  89. LLM to carry in every session. You can expose only the tools you need with
  90. three optional environment variables:
  91. | Env var | Effect |
  92. |---|---|
  93. | `GARMIN_TOOL_PROFILE` | A built-in subset by area: `minimal`, `health`, `activities`, `workouts`, `training`, `nutrition`, or `all` (the default). Combine several with commas, e.g. `health,training`. |
  94. | `GARMIN_ENABLED_TOOLS` | Comma-separated **allowlist** — if set, *only* these tools are registered. With a profile, these are **added** to it instead. |
  95. | `GARMIN_DISABLED_TOOLS` | Comma-separated **denylist** — listed tools are skipped. Ignored if an allowlist is set, unless a profile is also set; then it removes tools from the profile. |
  96. Tool names are case-insensitive. With none of them set, all tools register
  97. (unchanged default behaviour). Names that match no tool are ignored with a
  98. warning on stderr, which makes typos easy to spot. An unknown profile name
  99. stops the server at startup with the list of known profiles.
  100. ### Profiles
  101. | Profile | Tools | What it covers |
  102. |---|---:|---|
  103. | `minimal` | 20 | Recent activities with splits, daily stats, sleep, HRV, stress, body battery, training readiness and status |
  104. | `health` | 53 | Every health_wellness tool plus weight, body composition, blood pressure, hydration, women's health, fitness age, HRV and respiration trends |
  105. | `activities` | 41 | Activity list, detail, splits and edits; FIT analysis and power curve; gear; courses |
  106. | `workouts` | 26 | Workout library, upload, schedule and delete; the high-level builders; the calendar |
  107. | `training` | 38 | Training status, load, effect, VO2max, FTP, lactate threshold, endurance and hill scores, readiness, recovery time, personal records, race predictions, goals, badges |
  108. | `nutrition` | 23 | Food log, custom foods, daily nutrition settings, hydration, energy balance |
  109. Every profile also includes the identity and unit tools (`get_full_name`, `get_heart_rate_zones`, `get_unit_system`, `get_user_profile`, `get_userprofile_settings`), so the
  110. client can label the numbers it gets back.
  111. Example — a coaching session that needs training metrics and the workout tools:
  112. ```json
  113. "env": {
  114. "GARMIN_TOOL_PROFILE": "training,workouts"
  115. }
  116. ```
  117. Example — the health profile plus recent activities, without the write tools:
  118. ```json
  119. "env": {
  120. "GARMIN_TOOL_PROFILE": "health",
  121. "GARMIN_ENABLED_TOOLS": "get_activities,get_activity",
  122. "GARMIN_DISABLED_TOOLS": "add_weigh_in,add_weigh_in_with_timestamps,delete_weigh_ins,add_body_composition,add_hydration_data,set_blood_pressure"
  123. }
  124. ```
  125. Example — hand-pick tools without a profile:
  126. ```json
  127. "env": {
  128. "GARMIN_ENABLED_TOOLS": "get_sleep_data,get_stress_summary,get_activities"
  129. }
  130. ```
  131. ## High-level workout tools
  132. These builder tools let an LLM create and schedule workouts without writing raw Garmin JSON.
  133. ### `create_walk_run_workout`
  134. Creates a walk/run interval workout with optional heart-rate zone target.
  135. ```json
  136. {
  137. "name": "W3 Mié 2:2",
  138. "run_seconds": 120,
  139. "walk_seconds": 120,
  140. "repeats": 9,
  141. "warmup_min": 10,
  142. "cooldown_min": 8,
  143. "hr_zone": "Z3"
  144. }
  145. ```
  146. Returns: `{"status": "success", "workout_id": 1234567890, ...}`
  147. ### `create_z2_walk_workout`
  148. Creates a steady Z2 walking workout.
  149. ```json
  150. {
  151. "name": "Z2 Walk 45m",
  152. "duration_min": 45,
  153. "hr_min": 110,
  154. "hr_max": 130
  155. }
  156. ```
  157. Returns: `{"status": "success", "workout_id": 1234567890, ...}`
  158. ### `create_strength_workout`
  159. Creates a strength workout from a list of exercises. Each becomes a reps-based step, with the
  160. name kept in the step description. The name is also sent as `exerciseName`, but Garmin only
  161. retains that when it matches one of its own exercise keys (e.g. `FARMERS_CARRY`) — any other
  162. value is accepted and then stored empty.
  163. `category` is optional and passed straight through. Omit it and the key is left out of the
  164. payload entirely, which Garmin accepts. Supply it and it must be one of Garmin's exercise
  165. categories — anything else, including `OTHER` and `UNASSIGNED`, is rejected with
  166. `400 - Invalid category`. The full list is published at
  167. [`Exercises.json`](https://connect.garmin.com/web-data/exercises/Exercises.json).
  168. ```json
  169. {
  170. "name": "Full Body A",
  171. "exercises": [
  172. {"name": "Sentadillas", "sets": 3, "reps": 12, "rest_seconds": 90},
  173. {"name": "Flexiones", "sets": 3, "reps": 15, "rest_seconds": 60},
  174. {"name": "Peso muerto", "sets": 3, "reps": 10, "rest_seconds": 90},
  175. {"name": "Farmers Carry 40m", "sets": 3, "reps": 1, "rest_seconds": 90, "category": "CARRY"}
  176. ]
  177. }
  178. ```
  179. Returns: `{"status": "success", "workout_id": 1234567890, ...}`
  180. ### `schedule_week`
  181. Schedules multiple workouts in one call.
  182. ```json
  183. {
  184. "week": [
  185. {"date": "2026-05-12", "workout_id": 1234567890},
  186. {"date": "2026-05-14", "workout_id": 1234567891}
  187. ]
  188. }
  189. ```
  190. Returns: `{"status": "complete", "scheduled": [...]}`
  191. ### Full flow example
  192. ```text
  193. create_walk_run_workout(name="W3 Mié 2:2", run_seconds=120, walk_seconds=120,
  194. repeats=9, warmup_min=10, cooldown_min=8)
  195. → workout_id = 1560092011
  196. schedule_workout(workout_id=1560092011, date="2026-05-06")
  197. → OK
  198. ```
  199. After syncing your watch, the workout appears on the Forerunner 965 calendar.
  200. ### Raw `upload_workout` end conditions
  201. When building custom workout JSON for `upload_workout` or `upload_workouts`, the
  202. `endCondition.conditionTypeId` and `endCondition.conditionTypeKey` must match
  203. Garmin's canonical mapping. Garmin treats the numeric `conditionTypeId` as the
  204. source of truth; if the key and ID conflict, Garmin stores the condition that
  205. matches the ID.
  206. For example, this is invalid for a heart-rate end condition because ID `4` is
  207. `calories`, not `heart.rate`:
  208. ```json
  209. {
  210. "endCondition": {
  211. "conditionTypeId": 4,
  212. "conditionTypeKey": "heart.rate"
  213. },
  214. "endConditionValue": 145
  215. }
  216. ```
  217. Use ID `6` for heart rate:
  218. ```json
  219. {
  220. "endCondition": {
  221. "conditionTypeId": 6,
  222. "conditionTypeKey": "heart.rate"
  223. },
  224. "endConditionValue": 145
  225. }
  226. ```
  227. For a zone-based heart-rate end condition, use `endConditionZone` (1-5) on the
  228. same `endCondition` object and omit `endConditionValue`. If both are sent,
  229. Garmin keeps the zone and drops the value (verified against the production API
  230. on 2026-09-01):
  231. ```json
  232. {
  233. "endCondition": {
  234. "conditionTypeId": 6,
  235. "conditionTypeKey": "heart.rate",
  236. "endConditionZone": 2
  237. }
  238. }
  239. ```
  240. Common end-condition IDs:
  241. | ID | Key |
  242. |---:|---|
  243. | 1 | `lap.button` |
  244. | 2 | `time` |
  245. | 3 | `distance` |
  246. | 4 | `calories` |
  247. | 5 | `power` |
  248. | 6 | `heart.rate` |
  249. | 7 | `iterations` |
  250. | 8 | `fixed.rest` |
  251. | 9 | `fixed.repetition` |
  252. | 10 | `reps` |
  253. | 11 | `training.peaks.tss` |
  254. ### Raw `upload_workout` target types
  255. When building raw Garmin workout JSON, `targetType.workoutTargetTypeId` and
  256. `targetType.workoutTargetTypeKey` must use Garmin's canonical mapping. Garmin
  257. treats the numeric ID as authoritative: a mismatched payload such as
  258. `{"workoutTargetTypeId": 6, "workoutTargetTypeKey": "heart.rate"}` is stored as
  259. `pace.zone`, because ID `6` means `pace.zone`.
  260. For a custom heart-rate range, use target type ID `4` with `heart.rate.zone` and
  261. put the bpm range in `targetValueOne` / `targetValueTwo`. These value fields
  262. belong on the workout step, alongside `targetType`; do not nest them inside the
  263. `targetType` object:
  264. ```json
  265. {
  266. "targetType": {
  267. "workoutTargetTypeId": 4,
  268. "workoutTargetTypeKey": "heart.rate.zone"
  269. },
  270. "targetValueOne": 143,
  271. "targetValueTwo": 157
  272. }
  273. ```
  274. The same shape applies to a custom running pace range. Pace bounds use meters
  275. per second:
  276. ```json
  277. {
  278. "targetType": {
  279. "workoutTargetTypeId": 6,
  280. "workoutTargetTypeKey": "pace.zone"
  281. },
  282. "targetValueOne": 1.9607843,
  283. "targetValueTwo": 2.0833333
  284. }
  285. ```
  286. That example represents `8:00–8:30 min/km`. The lower numeric bound is listed
  287. first for consistency with the heart-rate example; Garmin normalizes either
  288. bound order. Garmin silently discards values nested inside `targetType`, leaving
  289. a pace target with no active range. The upload tools repair that unambiguous
  290. nesting mistake, but reject the request if nested and step-level values conflict.
  291. For a named Garmin HR zone, use the same target type with `zoneNumber` instead:
  292. ```json
  293. {
  294. "targetType": {
  295. "workoutTargetTypeId": 4,
  296. "workoutTargetTypeKey": "heart.rate.zone"
  297. },
  298. "zoneNumber": 3
  299. }
  300. ```
  301. Use either `zoneNumber` or `targetValueOne` / `targetValueTwo` on a target, not
  302. both. Garmin treats the named zone as authoritative and silently discards a
  303. coexisting custom range, so the upload tools reject that ambiguous shape.
  304. ## One-click Install (Claude Desktop)
  305. The easiest way to add this server to Claude Desktop is via the `.dxt` Desktop Extension file — no JSON editing required.
  306. ### Download and install
  307. 1. Download the latest `garmin-mcp.dxt` from the [Releases page](https://github.com/Taxuspt/garmin_mcp/releases).
  308. 2. Drag the `.dxt` file into the Claude Desktop window, **or** double-click it, **or** go to **Settings → Extensions → Install Extension** and select the file.
  309. 3. Claude Desktop will prompt you for optional configuration (token path, email, password).
  310. ### First-time authentication
  311. The extension installs and runs the server automatically, but you must authenticate with Garmin once before data can be fetched:
  312. ```bash
  313. uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth
  314. ```
  315. This saves OAuth tokens to `~/.garminconnect`. After that the server works without any credentials in the config.
  316. > **Note:** Tokens are valid for approximately 6 months. Re-run `garmin-mcp-auth` when they expire.
  317. ### Build the `.dxt` yourself
  318. ```bash
  319. bash scripts/build_dxt.sh # produces garmin-mcp.dxt in the repo root
  320. ```
  321. ---
  322. ## Setup
  323. ### Quick Start for MCP Clients
  324. The easiest way to use this MCP server with Claude Desktop, [Codex](https://openai.com/codex/), or another MCP client is to authenticate once before adding the server to your configuration.
  325. #### Prerequisites
  326. - Python 3.12+
  327. - Garmin Connect account
  328. - MFA may be required if enabled on your account
  329. #### Step 1: Pre-authenticate (One-time)
  330. Before adding the server to your MCP client, authenticate once in your terminal:
  331. ```bash
  332. # Install and run authentication tool
  333. uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth
  334. # You'll be prompted for:
  335. # - Email (or set GARMIN_EMAIL env var)
  336. # - Password (or set GARMIN_PASSWORD env var)
  337. # - MFA code (if enabled on your account)
  338. # OAuth tokens will be saved to ~/.garminconnect
  339. ```
  340. You can verify your credentials at any time with
  341. ```bash
  342. uv run garmin-mcp-auth --verify
  343. ```
  344. **Note:** You can also set credentials via environment variables:
  345. ```bash
  346. GARMIN_EMAIL=your@email.com GARMIN_PASSWORD=secret garmin-mcp-auth
  347. ```
  348. If you don't have MFA enabled you can also skip `garmin-mcp-auth` and pass `GARMIN_EMAIL` and `GARMIN_PASSWORD` as env variables directly to your MCP client, if supported. For better security, prefer the pre-authentication flow above and keep credentials out of MCP client configuration.
  349. #### Step 2: Configure Claude Desktop
  350. Add to your Claude Desktop MCP settings **WITHOUT** credentials:
  351. **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  352. **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  353. ```json
  354. {
  355. "mcpServers": {
  356. "garmin": {
  357. "command": "uvx",
  358. "args": [
  359. "--python",
  360. "3.12",
  361. "--from",
  362. "git+https://github.com/Taxuspt/garmin_mcp",
  363. "garmin-mcp"
  364. ]
  365. }
  366. }
  367. }
  368. ```
  369. **Important:** No `GARMIN_EMAIL` or `GARMIN_PASSWORD` needed in config! The server uses your saved tokens.
  370. #### Step 3: Restart your MCP client
  371. Your Garmin data is now available to your MCP client.
  372. For Codex and other clients, see the examples below.
  373. ---
  374. ### Using more than one Garmin account
  375. A single server process is bound to one Garmin account. To use several accounts
  376. at once, run **one server instance per account**, each with its own token
  377. directory, selected with the `GARMINTOKENS` environment variable.
  378. `GARMINTOKENS` defaults to `~/.garminconnect`. Point it somewhere else and the
  379. server reads and writes tokens there instead, leaving the default store
  380. untouched.
  381. #### Step 1: Authenticate each account into its own directory
  382. ```bash
  383. garmin-mcp-auth --token-path ~/.garminconnect-alice
  384. garmin-mcp-auth --token-path ~/.garminconnect-bob
  385. ```
  386. `--token-path` also accepts `$GARMINTOKENS`, so `GARMINTOKENS=~/.garminconnect-alice garmin-mcp-auth`
  387. is equivalent.
  388. #### Step 2: Declare one server per account
  389. ```json
  390. {
  391. "mcpServers": {
  392. "garmin-alice": {
  393. "command": "uvx",
  394. "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
  395. "env": {
  396. "GARMINTOKENS": "${HOME}/.garminconnect-alice"
  397. }
  398. },
  399. "garmin-bob": {
  400. "command": "uvx",
  401. "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
  402. "env": {
  403. "GARMINTOKENS": "${HOME}/.garminconnect-bob"
  404. }
  405. }
  406. }
  407. }
  408. ```
  409. Each server logs the directory it authenticates from on startup, so you can
  410. confirm the wiring:
  411. ```
  412. Trying to login to Garmin Connect using token data from directory '/home/you/.garminconnect-alice'...
  413. ```
  414. #### Notes
  415. - **No silent fallback.** If `GARMINTOKENS` points at a directory with no valid
  416. tokens and login fails, the server logs the failure and tool calls fail;
  417. HTTP `/readyz` remains unavailable (503). The server does not switch to the
  418. default token store, so a misconfigured second server cannot silently reuse
  419. the first account's session.
  420. - **`${HOME}` is expanded** even when an MCP client passes it through
  421. unresolved, and `~` works on Windows via `USERPROFILE`.
  422. - **Restrict write tools on secondary accounts.** Tools such as
  423. `upload_workout` and `schedule_workout` write to whichever account the server
  424. is bound to. Pair `GARMINTOKENS` with `GARMIN_ENABLED_TOOLS` (see
  425. [Tool Filtering](#tool-filtering)) to make an account read-only:
  426. ```json
  427. "env": {
  428. "GARMINTOKENS": "${HOME}/.garminconnect-bob",
  429. "GARMIN_ENABLED_TOOLS": "get_activities,get_activities_by_date,get_activity,get_activity_splits"
  430. }
  431. ```
  432. - **Token directories hold long-lived credentials.** They are created with
  433. owner-only permissions; keep them out of shared or synced folders.
  434. ---
  435. ### Development Setup
  436. 1. Install the required packages on a new environment:
  437. ```bash
  438. uv sync
  439. ```
  440. ## Running the Server
  441. ### Configuration
  442. Your Garmin Connect credentials are read from environment variables:
  443. - `GARMIN_EMAIL`: Your Garmin Connect email address
  444. - `GARMIN_EMAIL_FILE`: Path to a file containing your Garmin Connect email address
  445. - `GARMIN_PASSWORD`: Your Garmin Connect password
  446. - `GARMIN_PASSWORD_FILE`: Path to a file containing your Garmin Connect password
  447. - `GARMIN_IS_CN`: Set to `true` to use Garmin Connect China (garmin.cn) instead of the international version (default: `false`)
  448. - `GARMIN_FIT_DOWNLOAD_DIR`: Default directory for downloaded activity files. When set, skips the first-run setup prompt in `download_activity_file`.
  449. - `GARMIN_FIT_CONFIG`: Path to the persisted download-directory config file (default: `~/.garminconnect_fit_config.json`).
  450. File-based secrets are useful in certain environments, such as inside a Docker container. Note that you cannot set both `GARMIN_EMAIL` and `GARMIN_EMAIL_FILE`, similarly you cannot set both `GARMIN_PASSWORD` and `GARMIN_PASSWORD_FILE`.
  451. ### Transport
  452. By default the server communicates over **stdio**, which is what Claude Desktop, the MCP Inspector, and most local clients expect. To serve over **HTTP** instead (e.g. when running in a container or Kubernetes), set the transport via environment variables:
  453. - `GARMIN_MCP_TRANSPORT`: `stdio` (default), `streamable-http`, or `sse`
  454. - `GARMIN_MCP_HOST`: bind address for HTTP transports (default `127.0.0.1`; set to `0.0.0.0` only together with `GARMIN_MCP_HTTP_TOKEN` or behind an authenticating reverse proxy)
  455. - `GARMIN_MCP_PORT`: bind port for HTTP transports (default `8000`)
  456. - `GARMIN_MCP_HTTP_TOKEN`: shared secret for the HTTP transports. When set, every request to `/mcp`, `/sse` and `/messages/` must carry `Authorization: Bearer <token>`; anything else gets `401`. `/healthz` and `/readyz` stay open for probes. See [Protecting the HTTP endpoint](#protecting-the-http-endpoint).
  457. - `GARMIN_MCP_STATELESS_HTTP`: set to `true` to run `streamable-http` without sessions (default `false`). The MCP SDK drops a stateful session after 30 minutes idle, so the first call after an idle gap gets `404 Session not found`; some clients (including claude.ai custom connectors) report that as a failed tool call rather than re-initializing and retrying. Stateless mode has no sessions to expire. No tool in this server depends on session state, so nothing is lost. Recommended for long-lived remote deployments.
  458. - `GARMIN_MCP_CALL_TIMEOUT`: per-request timeout in seconds for calls to Garmin (default `90`). Garmin's API occasionally stalls a single request indefinitely; without this bound the call hangs until the MCP client's own timeout fires and reports the whole server as unresponsive. On timeout the tool returns a clear, retry-able error instead. Set to `0` to disable the bound.
  459. ```bash
  460. GARMIN_MCP_TRANSPORT=streamable-http garmin-mcp
  461. ```
  462. When an HTTP transport is selected:
  463. - MCP clients connect to the **`/mcp`** path (e.g. `http://localhost:8000/mcp`).
  464. - **`GET /healthz`** returns `ok` as soon as the server is up — use it as a **liveness** probe.
  465. - **`GET /readyz`** reports whether Garmin login has finished — use it as a **readiness** probe. It returns `200 {"status": "ready"}` once login succeeded, and `503` with `{"status": "pending"}` while login is still running or `{"status": "failed"}` if it failed (re-run `garmin-mcp-auth` and restart).
  466. #### Protecting the HTTP endpoint
  467. The HTTP transports expose full read/write access to the Garmin account, so
  468. the server binds to loopback by default. For anything reachable from other
  469. machines, set a shared secret and have the client send it as a bearer token:
  470. ```bash
  471. export GARMIN_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
  472. GARMIN_MCP_TRANSPORT=streamable-http GARMIN_MCP_HOST=0.0.0.0 garmin-mcp
  473. ```
  474. ```bash
  475. # rejected: 401 {"error": "unauthorized", ...}
  476. curl -i http://localhost:8000/mcp
  477. # accepted (the MCP handshake then proceeds as usual)
  478. curl -i -H "Authorization: Bearer $GARMIN_MCP_HTTP_TOKEN" http://localhost:8000/mcp
  479. ```
  480. Most MCP clients accept custom headers for remote servers (Claude Desktop and
  481. claude.ai connectors, the MCP Inspector, and the SDK clients all do); put the
  482. same `Authorization: Bearer …` header there. The comparison is constant-time.
  483. `/healthz` and `/readyz` never require the token, since they only report that
  484. the process is up and whether the Garmin login finished.
  485. Without the token the server still starts, but if `GARMIN_MCP_HOST` is not a
  486. loopback address it prints a warning on stderr that the account is exposed. A
  487. reverse proxy with its own authentication (nginx, Traefik, Authelia, etc.)
  488. remains a fine alternative; the token is the small, built-in option for the
  489. common self-hosted case.
  490. ### Garmin Connect China (garmin.cn)
  491. If you use Garmin Connect China (garmin.cn) instead of the international version, set the `GARMIN_IS_CN` environment variable to `true`:
  492. ```bash
  493. # Pre-authenticate with Garmin Connect China
  494. GARMIN_IS_CN=true garmin-mcp-auth
  495. # Or use the CLI flag
  496. garmin-mcp-auth --is-cn
  497. ```
  498. For Claude Desktop, add `GARMIN_IS_CN` to the `env` section:
  499. ```json
  500. {
  501. "mcpServers": {
  502. "garmin": {
  503. "command": "uvx",
  504. "args": [
  505. "--python",
  506. "3.12",
  507. "--from",
  508. "git+https://github.com/Taxuspt/garmin_mcp",
  509. "garmin-mcp"
  510. ],
  511. "env": {
  512. "GARMIN_IS_CN": "true"
  513. }
  514. }
  515. }
  516. }
  517. ```
  518. For Docker, add `GARMIN_IS_CN=true` to your `.env` file or uncomment it in `docker-compose.yml`.
  519. ### Testing the server locally with MCP Inspector
  520. The Inspector runs directly through npx without requiring installation. Run from the project root:
  521. ```bash
  522. npx @modelcontextprotocol/inspector uv run garmin-mcp
  523. ```
  524. You'll be able to inspect and test the tools.
  525. ### With Claude Desktop
  526. 1. Create a configuration in Claude Desktop:
  527. Edit your Claude Desktop configuration file:
  528. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  529. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  530. You have two options to run the MCP locally with Claude.
  531. #### Directly from github without cloning the repo:
  532. 1. Add this server configuration:
  533. ```json
  534. {
  535. "mcpServers": {
  536. "garmin": {
  537. "command": "uvx",
  538. "args": [
  539. "--python",
  540. "3.12",
  541. "--from",
  542. "git+https://github.com/Taxuspt/garmin_mcp",
  543. "garmin-mcp"
  544. ],
  545. "env": {
  546. "GARMIN_EMAIL": "YOUR_GARMIN_EMAIL",
  547. "GARMIN_PASSWORD": "YOUR_GARMIN_PASSWORD"
  548. }
  549. }
  550. }
  551. }
  552. ```
  553. You might have to add the full path to `uvx` you can check the full path with `which uvx`
  554. 2. Restart Claude Desktop
  555. #### Directly from your local copy of the repository:
  556. 1. Add this server configuration:
  557. ```
  558. {
  559. "mcpServers": {
  560. "garmin-local": {
  561. "command": "uv",
  562. "args": [
  563. "--directory",
  564. "<full path to your local repository>/garmin_mcp",
  565. "run",
  566. "garmin-mcp"
  567. ]
  568. }
  569. }
  570. }
  571. ```
  572. 2. Restart Claude Desktop
  573. ### With Codex
  574. Codex uses TOML for MCP server configuration. Add one of the following entries to `~/.codex/config.toml` after authenticating with `garmin-mcp-auth`.
  575. You can also ask your MCP-capable client to set this up for you. For example:
  576. ```text
  577. Install the Garmin MCP server from https://github.com/Taxuspt/garmin_mcp, authenticate with garmin-mcp-auth, and add it to my MCP configuration without storing my Garmin email or password.
  578. ```
  579. #### Directly from GitHub without cloning the repo
  580. ```toml
  581. [mcp_servers.garmin]
  582. command = "uvx"
  583. args = [
  584. "--python",
  585. "3.12",
  586. "--from",
  587. "git+https://github.com/Taxuspt/garmin_mcp",
  588. "garmin-mcp"
  589. ]
  590. ```
  591. #### Directly from your local copy of the repository
  592. ```toml
  593. [mcp_servers.garmin-local]
  594. command = "uv"
  595. args = [
  596. "--directory",
  597. "/full/path/to/garmin_mcp",
  598. "run",
  599. "garmin-mcp"
  600. ]
  601. ```
  602. Restart your MCP client after saving the file.
  603. ### With opencode
  604. [opencode](https://opencode.ai) auto-loads a project-level `opencode.json` when launched from a repository root, so contributors who clone this repo get the Garmin MCP wired up against the local source with no extra config.
  605. #### From a clone of this repository (recommended for development)
  606. This repo ships an [`opencode.json`](./opencode.json) that runs the MCP via `uv run garmin-mcp`, so it always tracks the working tree.
  607. ```bash
  608. git clone https://github.com/Taxuspt/garmin_mcp.git
  609. cd garmin_mcp
  610. uv sync # install dependencies
  611. garmin-mcp-auth # one-time Garmin login (skip if ~/.garminconnect already exists)
  612. opencode # launches with the garmin MCP attached
  613. ```
  614. Verify the server is connected:
  615. ```bash
  616. opencode mcp list
  617. # ● ✓ garmin connected
  618. # uv run garmin-mcp
  619. ```
  620. #### From any other directory (GitHub install)
  621. Add the server to your global opencode config at `~/.config/opencode/opencode.json` after running `garmin-mcp-auth`:
  622. ```json
  623. {
  624. "$schema": "https://opencode.ai/config.json",
  625. "mcp": {
  626. "garmin": {
  627. "type": "local",
  628. "command": [
  629. "uvx",
  630. "--python",
  631. "3.12",
  632. "--from",
  633. "git+https://github.com/Taxuspt/garmin_mcp",
  634. "garmin-mcp"
  635. ],
  636. "enabled": true,
  637. "timeout": 30000
  638. }
  639. }
  640. }
  641. ```
  642. Restart opencode after saving the file. The first `uvx` invocation downloads and caches the package, so the initial startup may take a few seconds.
  643. ### With Docker
  644. Docker provides an isolated and consistent environment for running the MCP server.
  645. #### Quick Start with Docker Compose (Recommended)
  646. 1. Create a `.env` file with your credentials:
  647. ```bash
  648. echo "GARMIN_EMAIL=your_email@example.com" > .env
  649. echo "GARMIN_PASSWORD=your_password" >> .env
  650. ```
  651. 2. Start the container:
  652. ```bash
  653. docker compose up -d
  654. ```
  655. 3. View logs to monitor the server:
  656. ```bash
  657. docker compose logs -f garmin-mcp
  658. ```
  659. #### Using Docker Directly
  660. ```bash
  661. # Build the image
  662. docker build -t garmin-mcp .
  663. # Run the container
  664. docker run -it \
  665. -e GARMIN_EMAIL="your_email@example.com" \
  666. -e GARMIN_PASSWORD="your_password" \
  667. -v garmin-tokens:/root/.garminconnect \
  668. garmin-mcp
  669. ```
  670. #### Using File-Based Secrets (More Secure)
  671. For enhanced security, especially in production environments, use file-based secrets instead of environment variables:
  672. 1. Create a secrets directory and add your credentials:
  673. ```bash
  674. mkdir -p secrets
  675. echo "your_email@example.com" > secrets/garmin_email.txt
  676. echo "your_password" > secrets/garmin_password.txt
  677. chmod 600 secrets/*.txt
  678. ```
  679. 2. Edit [docker-compose.yml](docker-compose.yml) and uncomment the secrets section:
  680. ```yaml
  681. services:
  682. garmin-mcp:
  683. environment:
  684. - GARMIN_EMAIL_FILE=/run/secrets/garmin_email
  685. - GARMIN_PASSWORD_FILE=/run/secrets/garmin_password
  686. secrets:
  687. - garmin_email
  688. - garmin_password
  689. secrets:
  690. garmin_email:
  691. file: ./secrets/garmin_email.txt
  692. garmin_password:
  693. file: ./secrets/garmin_password.txt
  694. ```
  695. 3. Start the container:
  696. ```bash
  697. docker compose up -d
  698. ```
  699. #### Handling MFA with Docker
  700. If you have multi-factor authentication (MFA) enabled on your Garmin account:
  701. 1. Run the authentication CLI with the service's token volume:
  702. ```bash
  703. docker compose run --rm --entrypoint garmin-mcp-auth garmin-mcp
  704. ```
  705. 2. When prompted, enter your MFA code:
  706. ```
  707. Garmin Connect MFA required. Please check your email/phone for the code.
  708. Enter MFA code: 123456
  709. ```
  710. 3. The OAuth tokens will be saved to the Docker volume (`garmin-tokens`), so you won't need to re-authenticate on subsequent runs.
  711. 4. After MFA setup, you can run the container normally:
  712. ```bash
  713. docker compose up -d
  714. ```
  715. #### Docker Volume Management
  716. The OAuth tokens are stored in a persistent Docker volume to avoid re-authentication:
  717. ```bash
  718. # List volumes
  719. docker volume ls
  720. # Inspect the tokens volume
  721. docker volume inspect garmin_mcp_garmin-tokens
  722. # Remove the volume (will require re-authentication)
  723. docker volume rm garmin_mcp_garmin-tokens
  724. ```
  725. #### Using with Claude Desktop via Docker
  726. To use the Dockerized MCP server with Claude Desktop, you can configure it to communicate with the container. However, note that MCP servers typically communicate via stdio, which works best with direct process execution. For Docker-based deployments, consider using the standard `uvx` method shown in the [With Claude Desktop](#with-claude-desktop) section instead.
  727. ## Usage Examples
  728. Once connected in Claude, you can ask questions like:
  729. - "Show me my recent activities"
  730. - "What was my sleep like last night?"
  731. - "How many steps did I take yesterday?"
  732. - "Show me the details of my latest run"
  733. - "Analyze my last ride's power zones and compare to my training zones"
  734. - "Show me my CTL, ATL, and TSB trend for the last 6 weeks"
  735. - "What was my power duration curve from yesterday's ride? Estimate my FTP."
  736. - "Analyze the FIT data from my last cycling activity — how was my shifting quality on the climbs?"
  737. - "Show me my HRV trend for the last 2 weeks and flag any recovery concerns"
  738. - "What's my season best 20-minute power and when did I set it?"
  739. ## Troubleshooting
  740. ### `get_training_effect` returns HTTP 403 for a valid activity
  741. Garmin's activity-details endpoint (`/activity-service/activity/{id}`) can
  742. return **403 Forbidden** even when the same activity is visible in list tools.
  743. `get_training_effect` now falls back to activity list search, which still
  744. includes aerobic/anaerobic training effect for recent activities.
  745. If the activity is older than the recent-search window, list the activity with
  746. `get_activities` / `get_activities_by_date` and retry, or use those list fields
  747. directly.
  748. ### `get_goals` returns no goals that exist in Garmin Connect
  749. Garmin's goal-service only returns goals created in Connect's current Goals UI
  750. (named distance/time targets such as a monthly cycling goal) when the request
  751. sends `Sec-Fetch-Site: same-origin` and uses a 1-based `start`. With
  752. `start=0`, it returns an empty list. python-garminconnect's `get_goals()` does not do both
  753. (through 0.3.16), so `get_goals` here calls `/goal-service/goal/goals`
  754. directly the way Connect's Goals page does, and uses the library call only as
  755. a fallback.
  756. ### "Failed to spawn process: No such file or directory"
  757. If Claude Desktop can't find `uvx`, it's because `uvx` is not in the PATH that Claude Desktop uses. To fix this:
  758. 1. Find where `uvx` is installed:
  759. ```bash
  760. which uvx
  761. ```
  762. 2. Use the full path in your configuration. For example, if `uvx` is at `/Users/username/.cargo/bin/uvx`:
  763. ```json
  764. {
  765. "mcpServers": {
  766. "garmin": {
  767. "command": "/Users/username/.cargo/bin/uvx",
  768. "args": [
  769. "--python",
  770. "3.12",
  771. "--from",
  772. "git+https://github.com/Taxuspt/garmin_mcp",
  773. "garmin-mcp"
  774. ]
  775. }
  776. }
  777. }
  778. ```
  779. ### Windows: Smart App Control blocks `uv` / `uvx`
  780. On Windows 11 with **Smart App Control** enabled, `uv.exe` / `uvx.exe` may be blocked when launching Garmin_MCP — including when `uv` tries to load an unsigned `garmin-mcp.exe` from a local `.venv`.
  781. This is **not** the same as Microsoft Defender Antivirus quarantine. Smart App Control is under:
  782. **Windows Security → App & browser control → Smart App Control**
  783. #### Symptoms
  784. - Smart App Control notification when running `uv`, `uvx`, or Claude Desktop with `command: "uvx"`
  785. - Claude Desktop fails to spawn the server even though `uvx` appears installed
  786. - Event Viewer → *Applications and Services Logs* → *Microsoft* → *Windows* → *CodeIntegrity* → *Operational* shows **CodeIntegrity Error 3077** mentioning `uv.exe` and `garmin-mcp.exe` (policy / Enterprise signing level)
  787. #### Confirm
  788. 1. Smart App Control is **On** (Evaluation or Enforcement).
  789. 2. Check the CodeIntegrity Operational log for event **3077** around the failed launch.
  790. 3. Defender “Virus & threat protection” history may be empty — that does not rule SAC out.
  791. #### Recoveries (prefer keeping Smart App Control on)
  792. 1. Install or reinstall `uv` via a packaged channel, then verify in PowerShell:
  793. ```powershell
  794. winget install --id=astral-sh.uv -e
  795. # or: scoop install main/uv
  796. uvx --version
  797. ```
  798. 2. Point Claude Desktop at the full path to `uvx.exe` (same idea as the PATH troubleshooting above), for example:
  799. ```json
  800. "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe"
  801. ```
  802. 3. If Enforcement still blocks loading `garmin-mcp.exe`, you may need an admin/policy exception for that binary path. Turning Smart App Control off globally is a last resort, not the default advice.
  803. 4. If local uvx remains blocked, use the Docker Compose install path instead.
  804. ### Login Issues
  805. If you encounter login issues:
  806. 1. Verify your credentials are correct
  807. 2. Check if Garmin Connect requires additional verification
  808. 3. Ensure the garminconnect package is up to date
  809. ### Logs
  810. For other issues, check the Claude Desktop logs at:
  811. - macOS: `~/Library/Logs/Claude/mcp-server-garmin.log`
  812. - Windows: `%APPDATA%\Claude\logs\mcp-server-garmin.log`
  813. ### Garmin Connect Multi-Factor Authentication (MFA)
  814. #### Understanding MFA with MCP Servers
  815. MCP servers run as background processes without direct terminal access. If your Garmin account has MFA enabled, you must authenticate once using the pre-authentication tool before the server can run.
  816. #### Recommended: Pre-Authentication Tool
  817. The easiest way to handle MFA is using the dedicated authentication tool:
  818. ```bash
  819. garmin-mcp-auth
  820. ```
  821. This saves OAuth tokens to `~/.garminconnect` for future use. The server will automatically use these tokens when running in Claude Desktop or other MCP clients.
  822. **Additional Options:**
  823. ```bash
  824. # Use environment variables for credentials
  825. GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=secret garmin-mcp-auth
  826. # Verify existing tokens
  827. garmin-mcp-auth --verify
  828. # Show where tokens are looked up, what is on disk, and whether they work
  829. garmin-mcp-auth --diagnose
  830. # Force re-authentication (e.g., when tokens expire)
  831. garmin-mcp-auth --force-reauth
  832. # Use custom token location
  833. garmin-mcp-auth --token-path ~/.garmin_tokens
  834. ```
  835. #### Alternative: Manual First Run
  836. You can provide credentials from files to the authentication CLI:
  837. ```bash
  838. # Store credentials in files for security
  839. echo "your_email@example.com" > ~/.garmin_email
  840. echo "your_password" > ~/.garmin_password
  841. chmod 600 ~/.garmin_email ~/.garmin_password
  842. # Run the authentication CLI before starting the server
  843. GARMIN_EMAIL_FILE=~/.garmin_email GARMIN_PASSWORD_FILE=~/.garmin_password \
  844. uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth
  845. # Enter MFA code when prompted
  846. # Tokens will be saved automatically
  847. # Now add to Claude Desktop config without credentials
  848. ```
  849. After initial authentication, configure Claude Desktop **without** credentials (tokens are already saved):
  850. ```json
  851. {
  852. "mcpServers": {
  853. "garmin": {
  854. "command": "uvx",
  855. "args": [
  856. "--python",
  857. "3.12",
  858. "--from",
  859. "git+https://github.com/Taxuspt/garmin_mcp",
  860. "garmin-mcp"
  861. ]
  862. }
  863. }
  864. }
  865. ```
  866. #### Using Docker with MFA
  867. If using Docker, follow the [Handling MFA with Docker](#handling-mfa-with-docker) section above for a streamlined experience with persistent token storage.
  868. #### Troubleshooting MFA
  869. **Error: "MFA required; run 'garmin-mcp-auth' before starting the server."**
  870. Solution:
  871. 1. Open terminal
  872. 2. Run: `garmin-mcp-auth`
  873. 3. Enter credentials and MFA code
  874. 4. Restart Claude Desktop
  875. **Token Expired**
  876. OAuth tokens expire periodically (approximately every 6 months). Re-authenticate:
  877. ```bash
  878. garmin-mcp-auth --force-reauth
  879. ```
  880. **Verify Tokens Work**
  881. ```bash
  882. garmin-mcp-auth --verify
  883. ```
  884. **`garmin-mcp-auth` succeeded, but the server still cannot log in**
  885. The server loads tokens only from `garmin_tokens.json` inside the token
  886. directory (`$GARMINTOKENS`, default `~/.garminconnect`). Its startup error says
  887. what it found there: no directory, no token file, a file it cannot read, or
  888. tokens Garmin rejected. The usual cause is the MCP client starting the server
  889. with a different `GARMINTOKENS` or `HOME` than the shell that ran
  890. `garmin-mcp-auth` (common with Claude Desktop on Windows), so the two resolve
  891. to different directories. Compare them with:
  892. ```bash
  893. garmin-mcp-auth --diagnose
  894. ```
  895. The `~/.garminconnect_base64` file that `garmin-mcp-auth` also writes is a copy
  896. for other garminconnect-based tools; the server does not read it.
  897. ## Testing
  898. This project includes comprehensive tests for all MCP tools. **All tests are currently passing (100%)**.
  899. ### Running Tests
  900. ```bash
  901. # Run unit and integration tests (default - uses mocked Garmin API, e2e tests are deselected)
  902. uv run pytest
  903. # Run only the integration tests
  904. uv run pytest tests/integration/
  905. # Run tests with verbose output
  906. uv run pytest tests/integration/ -v
  907. # Run a specific test module
  908. uv run pytest tests/integration/test_health_wellness_tools.py -v
  909. # Run end-to-end tests (requires real Garmin credentials).
  910. # Some of these create and delete foods, food logs and workouts in your account.
  911. uv run pytest tests/e2e/ -m e2e -v
  912. ```
  913. ### Test Structure
  914. - **Integration tests** (200+ tests): Test all MCP tools using FastMCP integration with mocked Garmin API responses
  915. - **End-to-end tests** (`tests/e2e/`): Test with real MCP server and Garmin API (requires valid credentials). Only run with `-m e2e`.
  916. ## Reinstalling from local path
  917. If you are working from a local checkout or fork:
  918. ```bash
  919. uv tool install --python 3.12 --force C:\Users\aresd\Desktop\programacion\garmin_mcp
  920. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.