Skip to main content
Glama
Sign In
deenesjakoruzh
garmin-coach-mcp

garmin-coach-mcp

by talvaknin744
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Local Garmin Coach MCP

Private, single-user Garmin coaching tools for Codex/ChatGPT desktop and Claude. The server is local stdio only: no Cloudflare, Render, public URL, account service, or hosting cost.

The runtime is based on etweisberg/garmin-connect-mcp at commit 87d0ea059fb67f1ce65ac05100df74c3c3777c84. It keeps the upstream AGPL-3.0 license and Taxuspt attribution in NOTICE.

Prerequisites

  • Node.js 20 or newer

  • pnpm 10.14.0

  • A Garmin Connect account and synced watch

Related MCP server: io.github.matisdsp/fartlek

Install

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth opens a dedicated visible Chrome profile. Log in manually, complete MFA, then press Enter in the terminal. The browser session stays under ~/.local/share/garmin-coach/browser-profile. Runtime CSRF values are read from the current authenticated page and never persisted or printed. Directories are 0700, files are 0600, password saving is disabled, and no username/password file is created.

Capture Garmin's profile-write contract

Garmin does not publish a stable heart-rate profile write API. The server refuses to guess it.

pnpm capture:profile-contract

The command loads Garmin's current app model, asks it to save the unchanged current default zones, and blocks the resulting PUT before delivery. It validates the route and exact unchanged body, then stores only a redacted method/path/field shape and supported scopes in ~/.local/state/garmin-coach/profile-write-contract.json with mode 0600.

If Garmin's shape cannot be proven, no contract is saved and profile writes remain disabled.

Connect Codex and ChatGPT desktop

Build first, then copy config/codex.toml.example into ~/.codex/config.toml, or add the equivalent server through ChatGPT desktop Settings > MCP servers. Codex CLI, the IDE extension, and ChatGPT desktop share local MCP configuration on the same host.

The example uses:

default_tools_approval_mode = "writes"

Both apply tools also have explicit approval_mode = "prompt". Restart the client after configuration and use /mcp to verify connection.

ChatGPT web cannot start this local stdio process. Use ChatGPT desktop/Codex for Garmin writes.

Connect Claude

Merge config/claude.json.example into Claude's MCP configuration, or run:

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

The filesystem lock permits only one local client to own the Garmin Chromium profile at a time. Stop the server in one client before using the other.

Tools

Tool

Garmin write

get_coaching_snapshot

No

get_training_program

No

preview_training_week

No

apply_training_week

Yes, approval required

verify_training_week

No

preview_hr_profile_update

No

apply_hr_profile_update

Yes, separate approval required

Safe workflow

  1. Call get_coaching_snapshot and compare it with Garmin Connect.

  2. Call preview_hr_profile_update.

  3. Review every field and approve the exact canonical proposal/hash.

  4. Call apply_hr_profile_update; then sync Garmin and visually verify watch zones.

  5. Call preview_training_week for one Sunday-starting week.

  6. Review its recovery evidence, complete payload, warnings, and hash.

  7. Call apply_training_week with the unchanged canonical proposal/hash.

  8. Call verify_training_week and confirm Monday/Friday are 135-149 bpm; Friday must display fixed 12% instructions.

  9. Retry both apply calls to prove idempotency.

Pain/injury or illness blocks workout writes. Recovery can keep, reduce, or skip; it never increases load. Workouts are never deleted automatically.

Garmin exposes Treadmill as a watch activity beneath Running, not as a structured-workout sport. Friday is therefore a running-compatible workout named Incline Walk 12%; start it from the watch's Treadmill activity. Its 12% incline cue and 135-149 bpm target remain explicit.

Approved HR profile

Field

Value

Maximum HR

189 bpm

Resting HR

55 bpm

Lactate threshold HR

181 bpm

Basis

Heart-rate reserve/custom BPM

Zone 1

122-134 bpm

Zone 2

135-149 bpm

Zone 3

150-162 bpm

Zone 4

163-176 bpm

Zone 5

177-189 bpm

These values are provisional: age 27, resting HR 55, estimated max HR 189, and manual LTHR 181. Automatic-detection flags are preserved. Future changes require another preview and approval.

Verification

Ordinary tests are offline and never call Garmin:

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

See spec.md for behavior and docs/architecture.md for trust boundaries.

License

AGPL-3.0. See LICENSE and NOTICE.

Available Tools

7 tools
apply_hr_profile_updateB
Idempotent

Apply one unchanged approved HR proposal through the captured Garmin browser contract, verify, and roll back on failure.

Inputs: hash (required), confirmed (required), canonicalProposal (required).

apply_training_weekC
Idempotent

Create, schedule, and read back one unchanged approved week. Never deletes workouts.

Inputs: hash (required), confirmed (required), canonicalProposal (required).

get_coaching_snapshotA
Read-onlyIdempotent

Read a privacy-filtered coaching snapshot: recovery, sleep, HRV, Body Battery, resting HR, load, recent activities, HR profile, and freshness.

Inputs: date.

get_training_programA
Read-onlyIdempotent

Return the exact five build weeks and week-six deload program.

Inputs: no named parameters.

preview_hr_profile_updateA
Read-onlyIdempotent

Read current HR settings and return every approved before/after field, canonical proposal, and hash. Performs no Garmin writes.

Inputs: no named parameters.

preview_training_weekA
Read-onlyIdempotent

Read current recovery data and build a complete canonical week without writing Garmin.

Inputs: weekStart (required), weekNumber (required), illness, painOrInjury, +1 more.

verify_training_weekC
Read-onlyIdempotent

Read Garmin and compare scheduled dates, managed workout steps, targets, descriptions, and IDs.

Inputs: canonicalProposal (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: training week verification, coaching snapshot, training program retrieval, preview/apply for training week, and preview/apply for HR profile. No two tools overlap in purpose; boundaries are clear even from the descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., verify_training_week, get_coaching_snapshot, preview_hr_profile_update). The verbs are semantically appropriate (get/preview for reads, apply for writes) and the noun phrases are uniformly structured.

    Tool Count5/5

    Seven tools cover the core coaching workflow without unnecessary redundancy. The count is well-scoped for the domain—neither sparse nor overwhelming—and each tool serves a clear, non-trivial purpose.

    Completeness5/5

    The tool set covers the full lifecycle for training week management (verify, get program, preview, apply) and HR profile updates (preview, apply), plus a snapshot for overall context. No obvious gaps exist; the server's stated scope is met without dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • DkwtMCP

      bynoe17
      A
      license
      A
      quality
      C
      maintenance
      Local MCP server that connects Claude Desktop with Garmin and Apple Health data to read training and recovery, estimate heart rate and pace zones, analyze performance, and create structured workouts.
      22
      MIT

    • garmin-athletics-mcp

      danielmcewan
      A
      license
      B
      quality
      C
      maintenance
      A private, read-only MCP server that gives local Codex and Claude Desktop sessions access to athletics and wellness data from a Garmin Forerunner 55. It runs locally over stdio, exposes read-only tools for daily health, recovery, performance, and workouts, and caches data in SQLite.
      8
      MIT

    • garmin-mcp

      Danielsuri
      A
      license
      Not graded
      quality
      B
      maintenance
      A local, single-user, read-only MCP server that gives Claude Code access to your Garmin health and training data, exposing tools for health snapshots, training status, run details, body metrics, and training analysis.
      1
      MIT