garmin-py

Garmin Connect for AI assistants and the command line. garmin-py exposes your health, activity, workout, and performance data as an MCP server (Claude Desktop, Claude Code, and any other MCP client) and as a CLI (garmin-cli) with table, JSON, and CSV output.

Read tools cover sleep, HRV, stress, body battery, training status/load, activities (including raw per-sample streams), planned workouts, race predictions, and personal records; write tools create and schedule structured workouts and manage activities. coach_snapshot assembles bounded recovery, load, execution, and calendar facts for AI coaching, while training_plan_reconcile links prescribed workouts to completed activities. The existing report_snapshot remains available for fixed morning, evening, and weekly reports.

Quick Start: Claude Desktop (one-click)

1. Download garmin-py-<version>.mcpb from the latest release.
2. Open it with Claude Desktop (or drag it into Settings → Extensions).
3. Enter your Garmin Connect email and password when prompted — they are stored in the operating system keychain, never in the conversation.

On first launch the bundle creates a private virtual environment under ~/.garmin-py/mcpb/ and installs the matching garmin-py release from PyPI (internet required once). Requirements: Python 3.10+ on PATH (macOS ships 3.9 — install from python.org or Homebrew).

If your account uses multi-factor authentication, the first tool call reports MFA_REQUIRED; Claude asks for the one-time code and completes the login with the submit_mfa_code tool. The session is saved, so this normally happens once.

Quick Start: Claude Code

uv tool install "garmin-py[mcp]"
garmin-cli login
claude mcp add --transport stdio garmin -- garmin-cli mcp-server

See MCP Server for other clients, HTTP transports, and the manual Claude Desktop config, and SKILL.md for the full tool reference.

CLI Installation

From PyPI (the distribution is garmin-py; the installed command is garmin-cli):

pip install garmin-py

Or from a local checkout:

pip install .

Verify the installation:

garmin-cli --version

Authentication

garmin-cli authenticates via the maintained python-garminconnect backend. The primary session-home surface is now GARMIN_HOME / --garmin-home; GARTH_HOME / --garth-home remains as a deprecated compatibility alias.

Interactive login (recommended)

garmin-cli login
# Email: your@email.com
# Password: (hidden)
# Login successful. Token store saved at: ~/.garminconnect/garmin_tokens.json

Use --email / --password to skip the prompts (useful for scripting):

garmin-cli login --email your@email.com --password yourpassword

Check login status at any time:

garmin-cli login status
# Logged in. Token store at: ~/.garminconnect/garmin_tokens.json

garmin-cli --json login status
# {"ok": true, "command": "login status", "count": 1, "data": [{"authenticated": true, "garmin_home": "..."}]}

Environment variables (alternative)

export GARMIN_EMAIL="your@email.com"
export GARMIN_PASSWORD="yourpassword"
garmin-cli health sleep --days 1

Custom session directory

garmin-cli --garmin-home /path/to/session login
garmin-cli --garmin-home /path/to/session health sleep --days 1

The default session directory is ~/.garminconnect. It is created with 0o700 permissions. Symlinks are rejected. Do not share this directory.

New sessions are stored as garmin_tokens.json inside GARMIN_HOME. If you still have an existing ~/.garth/garmin_tokens.json, the CLI will copy it into the new default home on first use. GARTH_HOME / --garth-home still work as deprecated aliases when you need to keep an older path explicitly.

Troubleshooting

Run the diagnostic command and paste its output when reporting an installation or authentication problem:

garmin-cli doctor
garmin-cli doctor --fast --format json  # skip the live session probe

The checks cover Python, configuration, token-store layout and permissions, the optional MCP install, the authenticated session, and MCP write-surface binding. Paths are home-relative where possible, and credentials are never included. MCP clients can run the same non-interactive checks with the read-only server_doctor tool.

Output Formats

All commands default to table output. Use --json or --format csv to change:

garmin-cli health sleep --days 7              # table (default)
garmin-cli --json health sleep --days 7       # JSON envelope
garmin-cli --format csv health sleep --days 7 # CSV

JSON envelope structure:

{
  "ok": true,
  "command": "health sleep",
  "date_range": {"from": "2026-03-05", "to": "2026-03-11"},
  "count": 7,
  "data": [
    {"date": "2026-03-05", "bedtime": "2026-03-04T23:10:00", "wake_time": "2026-03-05T06:25:00", "duration_hours": 7.2, "score": 78, ...}
  ]
}

Error envelope:

{
  "ok": false,
  "command": "health sleep",
  "error": "Rate limited by Garmin. Try again later.",
  "error_code": "RATE_LIMITED"
}

Exit code is always 0 on success, 1 on error.

Commands

Health

garmin-cli health sleep            [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health hrv              [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health weight           [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health body-battery     [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health stress           [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health spo2             [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health resting-hr       [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health readiness        [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health status           [--date DATE]
garmin-cli health steps            [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health daily-summary    [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health intensity-minutes [--date DATE | --from DATE --to DATE | --days N]

health daily-summary makes one API call per day — large date ranges may be slow.

health status returns Garmin's full training-load picture for the day: training status, acute/chronic load, acute:chronic workload ratio (ACWR), the chronic-load "tunnel", monthly load-focus buckets with their targets, and load-balance status.

AI coach

garmin-cli --json coach snapshot [--date DATE] [--baseline-days N] [--recent-daily-days N]
                                  [--include-extended-daily-baselines] [--sport TYPE]...

The default snapshot uses the 28 prior days for ranged signals and activities, nine prior days plus the current date for daily resting-HR and stress calls (leaving slack over the seven-sample baseline minimum for days without data), and at most 30 upstream requests. Baseline medians exclude the current date and require seven valid samples; the resting-HR and stress signals report the shorter daily window they were actually fetched over. Missing and stale values remain explicit in data_quality; the server returns neutral facts and does not assign a proprietary readiness score or decide whether a workout is safe.

Extended daily baselines are rejected if their estimated cost exceeds the 30-request cap. A terminal rate limit stops further Garmin calls while preserving completed sections with complete: false and aborted: true.

Activities

garmin-cli activity list             [--limit N] [--type TYPE] [--search TEXT] [--date DATE | --from DATE --to DATE | --days N]
garmin-cli activity get              ACTIVITY_ID [--detail] [--laps]  # --detail/-d shows sport-aware metrics; --laps appends lap data
garmin-cli activity laps             ACTIVITY_ID  # per-lap rows (run/bike: HR, power, cadence, start_time_gmt/local) or per-pool-length rows (lap_swimming)
garmin-cli activity zones            ACTIVITY_ID  # HR time-in-zone breakdown
garmin-cli activity weather          ACTIVITY_ID  # temperature, apparent temp, dew point, humidity, wind, condition
garmin-cli activity metrics-describe ACTIVITY_ID  # metric descriptors: key, unit, metricsIndex
garmin-cli activity detail-metrics   ACTIVITY_ID [--metric KEY]...  # raw per-sample time series (one row per sample)
garmin-cli activity download         ACTIVITY_ID [--fmt original|tcx|gpx|kml|csv] [--output PATH] [--force]
garmin-cli activity upload           FILE         # .fit / .gpx / .tcx
garmin-cli activity delete           ACTIVITY_ID [--confirm]
garmin-cli activity rename           ACTIVITY_ID NEW_NAME
garmin-cli activity set-type         ACTIVITY_ID TYPE_KEY  # e.g. running, cycling

--limit defaults to 20, max 100. --type filters by activity type key (e.g., running, cycling).

activity detail-metrics returns the raw recorded sample stream (~2000 rows for a typical activity; columns are the watch's metric keys such as directTimestamp, directHeartRate, directPower). Use repeatable --metric flags to select columns — activity metrics-describe lists what a given activity recorded. This is the data for intra-activity analyses such as first-half vs second-half aerobic decoupling.

activity download writes the activity file to disk (it never prints binary to stdout). --fmt defaults to original (the FIT file inside a ZIP archive); the default output name is activity_<id><ext> in the current directory, and an existing file is not overwritten unless --force is given. activity delete prompts for confirmation unless --confirm is passed. activity set-type accepts any typeKey from Garmin's live sport-type table (an unknown key is rejected before any write).

Detailed sport-specific metrics

activity get --detail projects metrics scoped by the activity's sport:

Every sport also carries the universal training-response fields: training_effect_label (Garmin's primary-benefit label such as TEMPO), training_load (per-activity EPOC-based load), and workout_id (the structured workout the activity executed, linking plan to execution). training_load also appears in activity list rows.

duration_min is moving time; elapsed_time_min is total wall-clock time, so elapsed - moving is the time stopped.

JSON and CSV output use a stable union schema — every key is present (with null for sport-inapplicable metrics) so downstream parsers see a stable shape. Table output is sport-aware: only sport-applicable columns appear, keeping tables dense.

When --detail is set, JSON also carries an unavailable array describing which registry-known metrics are not produced for this activity. Each entry has field, reason (not_applicable_to_sport or absent_in_response), and leg_index (set on multisport child contributions). Table output prints a single counts-only footnote; CSV output stays a flat tabular format and does not carry the manifest.

# Cycling detail
garmin-cli activity get 12345678 --detail

# Running detail with HR zones
garmin-cli activity get 12345678 --detail
garmin-cli activity zones 12345678

# Pool-swim per-length rows (auto-routes to typed_splits)
garmin-cli activity laps 12345678

# Cycling detail + lap power suite in one envelope
garmin-cli --json activity get 12345678 --detail --laps

Workouts

# Read
garmin-cli workout list     [--limit N]
garmin-cli workout get      WORKOUT_ID
garmin-cli workout calendar [--from DATE --to DATE | --days N | --ahead N]

# Write
garmin-cli workout create   FILE                   # JSON or YAML file
garmin-cli workout create   --stdin                # read JSON from stdin
garmin-cli workout update   WORKOUT_ID FILE        # partial update (only fields provided change)
garmin-cli workout delete   WORKOUT_ID [--confirm] # --confirm skips interactive prompt
garmin-cli workout schedule WORKOUT_ID DATE        # DATE = YYYY-MM-DD
garmin-cli workout unschedule SCHEDULE_ID [--confirm] # removes a calendar entry; SCHEDULE_ID is the workoutScheduleId returned by schedule

--ahead N shows the next N days of planned workouts (future-facing). --days N shows past N days.

YAML input is supported out of the box. See SKILL.md for the full workout JSON schema reference and step/target types.

Performance

garmin-cli performance thresholds
garmin-cli performance zones
garmin-cli performance vo2max
garmin-cli performance race-predictions
garmin-cli performance endurance-score [--date DATE | --from DATE --to DATE | --days N]
garmin-cli performance hill-score      [--date DATE | --from DATE --to DATE | --days N]
garmin-cli performance personal-records

performance endurance-score and performance hill-score make one API call per day — large date ranges may be slow.

performance personal-records returns all-time PRs (fastest 1 km through marathon, longest run/ride, biggest climb, best 20-min power, step records) with a human-readable label; typeIds Garmin has not documented publicly carry label: null with the raw value.

Devices

garmin-cli device list  # registered devices: device_id, display_name, device_type, last_sync_time

Normalized JSON Schemas

Recent fixes normalized several JSON payloads for agent-safe output:

• performance vo2max returns date, vo2max, sport
• performance zones returns sport, lt_hr_bpm, lt_pace
• workout calendar includes compatibility id plus explicit workout_id and workout_schedule_id
• workout get includes recursive segments, compatibility steps/steps_summary, and a write_projection only when the workout fits the simplified write schema
• health hrv reads lastNightAvg and still falls back to legacy lastNight

Date Range Options

Maximum range: 90 days. Conflicting options (e.g., --date with --days) produce a clear error.

Examples

# Last week of sleep data
garmin-cli health sleep --days 7

# HRV for a specific date range
garmin-cli health hrv --from 2026-03-01 --to 2026-03-10

# List recent running activities as CSV
garmin-cli --format csv activity list --limit 10 --type running

# Activities from a specific date range
garmin-cli activity list --from 2026-03-01 --to 2026-03-31

# Activities from the past 7 days
garmin-cli activity list --days 7

# Upcoming planned workouts
garmin-cli workout calendar --ahead 7

# Create a workout from a JSON file
garmin-cli --json workout create my_workout.json

# Create and schedule a workout via stdin
echo '{"name":"Easy Run","sport":"running","steps":[{"type":"interval","duration":{"type":"time","value":1800},"target":{"type":"heart.rate.zone","zone":2}}]}' \
  | garmin-cli --json workout create --stdin

# Schedule an existing workout
garmin-cli --json workout schedule 12345678901 2026-04-01

# All performance thresholds
garmin-cli performance thresholds

# Agent use: JSON output for scripting
garmin-cli --json health hrv --date 2026-03-11
garmin-cli --json activity list --limit 5

Error Codes

MCP Server

The MCP server exposes primitive health, activity, workout, performance, and device tools plus AI-coaching orchestration tools. coach_snapshot returns a bounded evidence packet, training_plan_reconcile compares the calendar with detailed activities, and training_plan_preview provides a no-write diff before the destructive training_plan_apply or training_plan_reschedule tools. Existing workout and activity write tools remain available. See SKILL.md for complete contracts and limits.

Synthetic Claude coaching workflow

1. Claude calls coach_snapshot and explains the recovery, load, plan, provenance, and any missing-data facts without inventing a readiness score.
2. Claude calls training_plan_reconcile in summary mode to separate exact workout associations from explicitly inferred or ambiguous matches.
3. If the user asks for a changed plan, Claude builds the strict plan object and calls training_plan_preview. Preview performs live reads only.
4. Claude shows the diff and asks for approval in the client. Only after approval should the client invoke training_plan_apply; the server does not treat an agent-supplied boolean as human approval.
5. Apply rechecks live state, creates and verifies destinations first, removes source schedules last, and reports complete, compensated, partial, or unknown truthfully.

training_plan_reconcile(detail="targets") adds HR, pace, power, and cadence target comparisons for matched running and cycling activities. It uses HR-zone and lap summaries first, fetches stride-downsampled streams only when required (at most 10 streams per call and 1000 samples per stream), and reports per-target coverage and data quality. Missing sensors and unsupported sports remain explicit insufficient_data states rather than failure verdicts. Apply tools can mutate the Garmin calendar and rely on the MCP client's destructive-tool approval UX.

Resources and prompts

MCP clients can preload two resources:

• garmin://server/manifest describes the runtime tool inventory, annotations, error recovery contracts, envelopes, and response limits.
• garmin://athlete/profile returns a cached, bounded thresholds, VO2max, race-prediction, and 7/28-day load snapshot. An unauthenticated read returns a structured unauthenticated body.

The server also publishes connection-time instructions with the authentication, response, error, limit, and write-approval contracts. Every typed tool envelope advertises the same contract through its machine-readable outputSchema.

Two URI templates expose the most-read entities without a tool round trip:

• garmin://activity/{id} returns the serialized activity_get envelope.
• garmin://health/sleep/{date} returns the serialized one-day health_sleep envelope for an ISO date.

Four content-only prompts guide common workflows: weekly_training_review, recovery_check, compare_recent_activities, and plan_next_week. The planning prompt explicitly requires human confirmation before invoking destructive apply tools.

Large MCP reads are bounded. activity_laps(activity_id, offset=0) returns at most 100 rows and supplies total, truncated, and next_offset paging metadata. activity_detail_metrics(activity_id, metrics="", max_samples=1000) accepts 100–5000 samples and deterministically samples the whole stream by stride, reporting samples_total, samples_returned, and stride.

Installation

The package is published on PyPI as garmin-py (the CLI command remains garmin-cli). The recommended install method is uv tool install, which places the binary in ~/.local/bin — a stable, venv-independent location that desktop applications can access without macOS sandbox issues:

uv tool install "garmin-py[mcp]"

Or from a source checkout:

uv tool install --editable "/path/to/garmin-py[mcp]"

To uninstall:

uv tool uninstall garmin-py

Avoid pointing MCP clients at a binary inside a project virtualenv (e.g. .venv/bin/garmin-cli). On macOS, desktop applications run in a sandbox and cannot read pyvenv.cfg inside directories they have not been granted access to, which causes a fatal Python startup error:

PermissionError: [Errno 1] Operation not permitted: '/path/to/.venv/pyvenv.cfg'

The uv tool install approach avoids this entirely. Alternatively, grant Claude Desktop Full Disk Access in System Settings → Privacy & Security → Full Disk Access.

Claude Desktop

The one-click .mcpb bundle (see Quick Start) is the recommended install. To configure manually instead, add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOU/.local/bin/garmin-cli",
      "args": ["mcp-server"]
    }
  }
}

With a custom session directory:

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOU/.local/bin/garmin-cli",
      "args": ["--garmin-home", "/path/to/.garminconnect", "mcp-server"]
    }
  }
}

Claude Code

claude mcp add --transport stdio garmin -- garmin-cli mcp-server

ChatGPT (via MCP bridge)

ChatGPT does not natively support MCP. To connect, run the server with an HTTP transport and use an MCP-to-OpenAI bridge such as mcp-openai-bridge or a similar proxy:

# Start the MCP server with streamable HTTP
garmin-cli mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

Then point the bridge at http://127.0.0.1:8000/mcp and configure it as a ChatGPT plugin or custom GPT action. Refer to the bridge project's documentation for setup details.

HTTP Transports

SSE and streamable HTTP use the MCP SDK's built-in HTTP server. --host defaults to 127.0.0.1 (loopback only).

Streamable HTTP (recommended for remote clients):

garmin-cli mcp-server --transport streamable-http --port 8000

SSE (for clients that require it):

garmin-cli mcp-server --transport sse --port 8000

Optional HTTP flags: --sse-path, --message-path (SSE only), --streamable-http-path, --stateless-http, --json-response (streamable-http only).

Bearer-token gate on non-loopback binds

Binding to any non-loopback address (--host 0.0.0.0 or an external interface) requires a bearer token. The server refuses to start otherwise.

export GARMIN_MCP_BEARER_TOKEN="<a-long-random-token>"
garmin-cli mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

When the token is set and the bind is non-loopback, the MCP SDK gates every tool call (read and write) through Authorization: Bearer <token> at the transport layer. Loopback binds (127.0.0.1, ::1, localhost) and the stdio transport are not gated -- they are trusted to the same degree as the shell user running the process.

TLS is expected to be terminated by a reverse proxy in front of the server; the built-in HTTP listener is plain HTTP.

For remote clients, prefer a dedicated session directory with --garmin-home rather than exporting credentials into another process.

See SKILL.md for the full tool list and parameter reference.

Development

pip install -e ".[dev]"
pytest tests/                 # unit and offline contract tests
pytest tests/ --e2e           # add read-only live e2e tests

To run MCP server tests, also install the mcp extra:

pip install -e ".[dev,mcp]"

E2E tests make real Garmin Connect API calls. They require a valid garmin_tokens.json session in ~/.garminconnect (or GARMIN_HOME; GARTH_HOME still works as an alias). Set E2E_RATE_LIMIT_SECONDS (default: 5) to adjust the inter-request delay.

Contract tests and fixtures

The default suite includes offline CLI and MCP contract flows backed by sanitized JSON payloads under tests/fixtures/backend/:

pytest tests/test_contract/

To refresh read fixtures against an authenticated account, run:

pytest tests/ --e2e --record-fixtures

--record-fixtures is rejected unless --e2e is also present. Recording occurs at the backend function boundary and redacts identity (names, user/owner ids, coordinates), location, profile-image, token, password, and secret key fragments before deterministic, sorted JSON is written. Review every fixture diff before committing it.

Tests that write to Garmin require a second opt-in and are never part of the default or ordinary --e2e run:

pytest tests/e2e/test_calendar_probe_e2e.py --e2e --e2e-writes

That probe creates, schedules, unschedules, and deletes a temporary workout. It is intended for maintainer-run identifier verification only.