garmin-connect-api 0.2.0__tar.gz

garmin_connect_api-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.env
+tokens/
+*.fit
+!tests/fixtures/*.fit

garmin_connect_api-0.2.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.2.0 (2026-10-19)
+
+First public release. 0.1.0 was prepared but never published; its contents are listed below
+under "Foundations".
+
+### Added
+
+Five features, each checked against a real account.
+
+- **Laps and lengths.** `get_activity_laps` gives a run's or ride's laps, and a pool swim's pace
+  per 100 of the pool's own unit (yards in a yard pool), with first half against second half and
+  the fastest and slowest stretch. Ride averages use moving time, as Garmin's own do.
+- **Swim, run and ride workouts.** `create_endurance_workout` builds steps that end on a time, a
+  distance or the lap button, with repeats; runs and rides take pace, speed, heart-rate, power or
+  cadence targets; swims take a stroke, equipment, a pool length and rests on the wall.
+- **Trends.** `get_trend` follows one of twelve metrics (steps, resting heart rate, sleep and sleep
+  score, HRV, readiness, stress, body battery, weight, body fat, running and cycling VO2 max) over
+  up to two years, daily, weekly or monthly, usually in one request.
+- **Editing sets.** `edit_activity_sets` corrects the exercise, reps or weight of a strength
+  activity's sets, or deletes sets, for when a watch guesses the exercise wrong.
+- **Named records.** Personal records now carry a name, a unit and a readable value, such as
+  "Fastest 1 km run, 4:47.5", instead of Garmin's bare type number.
+
+### Foundations
+
+- **Library, HTTP service and MCP server over one core.** The MCP tools are generated from the
+  FastAPI routes, so every endpoint is a tool with the same name and description.
+- **Read:** activities with per-set strength detail and training volume; daily health (steps,
+  heart rate, stress as minutes per band, body battery, sleep with stages, HRV, training readiness
+  and status); every weigh-in with body composition; original activity files.
+- **Write:** strength workouts onto the calendar, scheduled and pushed to a watch; completed
+  strength sessions as FIT activities with their sets; weigh-ins with full body composition as
+  FIT weight-scale files; activity renames and deletions.
+- **Every MCP tool is annotated** with a title and whether it reads, adds, or deletes and
+  overwrites, so clients can ask before the destructive ones.
+- **Safety:** passwords are typed only at `garmin login`; rate limits stop every call path instead
+  of retrying; the local service refuses cross-origin writes and foreign host names, and needs a
+  key beyond localhost.

garmin_connect_api-0.2.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use garmin-connect-api in research, please cite it as below."
+title: "garmin-connect-api: read and write Garmin Connect from Python, HTTP or an MCP client"
+type: software
+authors:
+  - name: "garmin-connect-api contributors"
+repository-code: "https://github.com/happyc0der/garmin-connect-api"
+url: "https://github.com/happyc0der/garmin-connect-api"
+license: MIT
+version: 0.2.0
+date-released: 2026-10-19
+keywords:
+  - Garmin Connect
+  - fitness
+  - strength training
+  - Model Context Protocol
+  - FIT

garmin_connect_api-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 happyc0der
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

garmin_connect_api-0.2.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.5
+Name: garmin-connect-api
+Version: 0.2.0
+Summary: Read and write Garmin Connect from Python, HTTP or an MCP client: activities, strength sets, health data, workouts, weigh-ins
+Project-URL: Homepage, https://github.com/happyc0der/garmin-connect-api
+Project-URL: Repository, https://github.com/happyc0der/garmin-connect-api
+Project-URL: Issues, https://github.com/happyc0der/garmin-connect-api/issues
+Project-URL: Changelog, https://github.com/happyc0der/garmin-connect-api/blob/main/CHANGELOG.md
+Author: happyc0der
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,fit,fitness,garmin,garmin-connect,mcp,model-context-protocol,strength-training
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp<5,>=4.0
+Requires-Dist: fit-tool<1,>=0.9.13
+Requires-Dist: garminconnect<0.4,>=0.3.19
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn>=0.32
+Description-Content-Type: text/markdown
+
+# garmin-connect-api
+
+Read and write Garmin Connect from an MCP client such as Claude, from Python, or over a local HTTP
+API: activities with per-set strength detail, daily health data, planned workouts, completed
+strength sessions, and weigh-ins with full body composition.
+
+<!-- mcp-name: io.github.happyc0der/garmin-connect-api -->
+
+> **Unofficial.** Not affiliated with or endorsed by Garmin. It uses the same private endpoints as
+> the Garmin Connect website, through [python-garminconnect](https://github.com/cyberjunky/python-garminconnect),
+> because Garmin offers no public API for individuals. Those endpoints can change without notice,
+> and using them is not sanctioned by Garmin's terms. It is meant for your own account and your
+> own data.
+
+## Status
+
+v0.2. Reads activities with per-set strength detail, laps and pool-swim lengths, daily health,
+trends over up to two years and named personal records; writes strength, run, ride and swim
+workouts, completed strength sessions, set corrections and weigh-ins with body composition. 41
+tools, every one checked against a real account. Bug reports and feature requests go to
+[GitHub Issues](https://github.com/happyc0der/garmin-connect-api/issues).
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer.
+
+**1. Log in once**, at a terminal:
+
+```bash
+uvx --from garmin-connect-api garmin login
+```
+
+This is the only place a password is ever typed. It asks for your Garmin email, password and any
+multi-factor code, then stores tokens in `~/.garmin-api/default`, readable by your user only.
+Nothing else ever prompts for a password; without tokens, every tool says to run this.
+
+**2. Add the server to your MCP client.**
+
+Claude Code:
+
+```bash
+claude mcp add --scope user --transport stdio garmin -- uvx garmin-connect-api
+```
+
+Claude Desktop, in `claude_desktop_config.json` (in `~/Library/Application Support/Claude/` on
+macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "garmin": {
+      "command": "uvx",
+      "args": ["garmin-connect-api"]
+    }
+  }
+}
+```
+
+**3. Ask.** "How did I sleep this week?", "Did my pace hold up in yesterday's swim?",
+"How has my resting heart rate moved since summer?", "Show my last strength session's sets, and
+change sets 3 to 5 to dumbbell rows", "Schedule a swim for Thursday: 200 easy, then 8 x 100 free
+on 20 seconds rest, in a 25-yard pool".
+
+## What it can do
+
+41 tools, each annotated so your client knows which only read (27), which add something (8) and
+which delete or overwrite (6), and can ask before running those.
+
+| Read | Write |
+| --- | --- |
+| Activities, filtered by type and date | Create a strength workout, schedule it, push it to a watch |
+| Per-set strength detail: exercise, reps, weight | Create a run, ride or pool swim workout, with targets |
+| Laps for runs and rides; pace per 100 for pool swims | Log a completed strength session, with every set |
+| A day in one answer: steps, heart rate, stress, body battery, sleep, HRV, readiness | Correct a session's sets: exercise, reps, weight |
+| Trends over up to two years: twelve metrics, daily, weekly or monthly | Record a weigh-in, or a full body composition reading |
+| Personal records, named and in units | Rename an activity or change its description |
+| Every weigh-in with body composition | Delete an activity, workout or weigh-in |
+| Planned workouts and the calendar | |
+| Garmin's 1,527-exercise catalogue, offline | |
+
+Four tools are written for a model rather than mirrored from an endpoint: `garmin_status` checks
+the login without calling Garmin, `find_exercise` finds Garmin's name for a lift, and
+`recent_strength_sessions` and `week_summary` answer common questions in one call.
+
+**Logging a finished workout** is the write Garmin's own developer programme has never offered. A
+session is encoded as a FIT activity file with set messages and uploaded, so it appears in Garmin
+Connect as a Strength Training activity, exercise by exercise.
+
+**Body composition** from a smart scale (fat, water, skeletal muscle, bone, BMI, basal metabolic
+rate, visceral fat) is written as a FIT weight-scale file, the way Garmin's own Index scales do it.
+A plain weigh-in carries weight alone.
+
+## Example output
+
+Answers come back compact, summarised the way a person would read them. These are from made-up
+data in the shapes Garmin returns.
+
+"Did my pace hold up in yesterday's swim?" calls `get_activity_laps`:
+
+```json
+{
+  "sport": "lap_swimming",
+  "pool_length": 25.0,
+  "pool_unit": "m",
+  "summary": {
+    "lengths": 80,
+    "distance": 2000.0,
+    "average_pace": "1:52/100m",
+    "first_half_pace": "1:50/100m",
+    "second_half_pace": "1:54/100m",
+    "by_stroke": {"FREESTYLE": 1800.0, "BACKSTROKE": 200.0},
+    "fastest_segment": {"lengths": "5-8", "pace": "1:44/100m"},
+    "slowest_segment": {"lengths": "77-80", "pace": "2:01/100m"}
+  }
+}
+```
+
+"How has my resting heart rate moved since summer?" calls `get_trend`, which rolls a long range
+into weeks:
+
+```json
+{
+  "metric": "resting_hr",
+  "unit": "bpm",
+  "aggregation": "week",
+  "summary": {
+    "days_with_data": 88,
+    "average": 54.2,
+    "min": 49.0,
+    "max": 61.0,
+    "first_period_average": 57.3,
+    "last_period_average": 51.6,
+    "change": -6.0
+  }
+}
+```
+
+## Before you write anything
+
+- **Activities you log may be shared automatically.** If your Garmin account is connected to Strava
+  or another app, an uploaded session can be posted there too, and deleting it from Garmin does not
+  delete it there.
+- **Rate limits are taken seriously.** Garmin puts Cloudflare and per-account rate limits in front
+  of its login, and a run of failed logins can lock an account out for a day or more. Nothing here
+  retries a login, and a rate limit stops every call path rather than being retried. If you see
+  one, wait.
+- **Exercises need Garmin's own names**, such as `BENCH_PRESS` / `BARBELL_BENCH_PRESS`. Every write
+  checks them against the catalogue first and suggests near misses, so a typo fails with a useful
+  message rather than Garmin's bare 400. Common gym names work in search: "rdl", "ohp", "pull ups".
+- **Sessions and body-composition readings need a timezone offset**, or a 7am reading would land
+  hours out. They are refused without one.
+
+## Command line
+
+```bash
+garmin doctor                          # setup check, no network
+garmin activities --type strength_training --limit 5
+garmin sets <activity-id>              # per-set detail
+garmin day 2026-10-18                  # one day of health data
+garmin exercises "lat pulldown"        # search the catalogue, offline
+garmin workout create workout.json     # plan a strength workout
+garmin log-session session.json        # log a completed one
+garmin encode-session session.json     # build its FIT file without uploading
+garmin decode-fit activity.zip         # read sets out of a Garmin export
+garmin serve                           # the HTTP API on 127.0.0.1:8765
+```
+
+Run them with `uvx --from garmin-connect-api garmin ...`, or install with
+`uv tool install garmin-connect-api`. Example specs:
+[session.json](https://github.com/happyc0der/garmin-connect-api/blob/main/examples/session.json),
+[workout.json](https://github.com/happyc0der/garmin-connect-api/blob/main/examples/workout.json).
+
+An encoded session file can also be imported by hand on the Garmin Connect website, if you would
+rather nothing logged in on your behalf.
+
+## Python library
+
+```python
+from datetime import datetime, timedelta, timezone
+from garmin_api.services import activities, health, uploads
+from garmin_api.models.workouts import (
+    StrengthSessionSpec, StrengthSessionExercise, StrengthSessionSet,
+)
+
+for activity in activities.list_activities(limit=5, activity_type="strength_training"):
+    sets = activities.get_sets(activity.activity_id)
+    print(activity.name, sets.total_volume_kg, "kg")
+
+print(health.day("2026-10-18").steps)
+
+uploads.log_strength_session(StrengthSessionSpec(
+    name="Push A",
+    start_time=datetime(2026, 10, 18, 7, 0, tzinfo=timezone(timedelta(hours=-4))),
+    exercises=[StrengthSessionExercise(
+        category="BENCH_PRESS",
+        exercise_name="BARBELL_BENCH_PRESS",
+        sets=[StrengthSessionSet(reps=10, weight_kg=60.0, rest_s=120)],
+    )],
+))
+```
+
+Responses are pydantic models with Garmin's inconsistencies ironed out: kilograms rather than
+grams, timezone-aware instants, snake_case throughout. Garmin's own payload is still on `raw` when
+something is not mapped.
+
+## HTTP API
+
+`garmin serve` runs the same API on `127.0.0.1:8765`, with interactive docs at `/docs`. The MCP
+tools are generated from these routes, so the two cannot drift apart. Because it can write to your
+account, the service refuses writes from web pages open in your browser and requests naming any
+host but `localhost`, which defeats DNS rebinding. Binding beyond localhost requires
+`GARMIN_API_KEY`.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `GARMINTOKENS` | Where tokens are stored. Defaults to `~/.garmin-api/default`. |
+| `GARMIN_API_KEY` | Required to bind the HTTP service beyond localhost. |
+| `GARMIN_API_HOSTS` | Extra host names the HTTP service answers to, comma-separated. |
+
+## Development
+
+```bash
+git clone https://github.com/happyc0der/garmin-connect-api
+cd garmin-connect-api
+uv sync
+uv run pytest
+```
+
+231 offline tests, needing no network and no account, run on Linux, macOS and Windows. They cover the models against real Garmin
+response shapes, the FIT codec's round trip, every one of the 1,527 catalogue exercises against
+the FIT profile, the HTTP routes, and every MCP tool's output against its own advertised schema,
+which strict clients enforce.
+
+Tests against a real account are opt-in, and the ones that create data need a second opt-in:
+
+```bash
+GARMIN_LIVE=1 uv run pytest tests/live                      # read only
+GARMIN_LIVE=1 GARMIN_LIVE_WRITE=1 uv run pytest tests/live  # creates, then deletes
+```
+
+## Why the unofficial route
+
+Garmin's official Connect Developer Program is for businesses, has no endpoint that uploads a
+completed activity, and was closed to new applicants in 2026. The aggregators that wrap it cost
+hundreds of dollars a month and are read-only or plans-only. So this uses the endpoints Garmin's
+own website uses, gently: no polling, no retries on a rate limit.
+
+## Citing
+
+If you use this in research, cite it with the metadata in [CITATION.cff](https://github.com/happyc0der/garmin-connect-api/blob/main/CITATION.cff);
+GitHub's "Cite this repository" button formats it.
+
+## Licence
+
+MIT. Garmin and Garmin Connect are trademarks of Garmin Ltd., used here only to say what this
+works with.

garmin_connect_api-0.2.0/README.md

@@ -0,0 +1,258 @@
+# garmin-connect-api
+
+Read and write Garmin Connect from an MCP client such as Claude, from Python, or over a local HTTP
+API: activities with per-set strength detail, daily health data, planned workouts, completed
+strength sessions, and weigh-ins with full body composition.
+
+<!-- mcp-name: io.github.happyc0der/garmin-connect-api -->
+
+> **Unofficial.** Not affiliated with or endorsed by Garmin. It uses the same private endpoints as
+> the Garmin Connect website, through [python-garminconnect](https://github.com/cyberjunky/python-garminconnect),
+> because Garmin offers no public API for individuals. Those endpoints can change without notice,
+> and using them is not sanctioned by Garmin's terms. It is meant for your own account and your
+> own data.
+
+## Status
+
+v0.2. Reads activities with per-set strength detail, laps and pool-swim lengths, daily health,
+trends over up to two years and named personal records; writes strength, run, ride and swim
+workouts, completed strength sessions, set corrections and weigh-ins with body composition. 41
+tools, every one checked against a real account. Bug reports and feature requests go to
+[GitHub Issues](https://github.com/happyc0der/garmin-connect-api/issues).
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer.
+
+**1. Log in once**, at a terminal:
+
+```bash
+uvx --from garmin-connect-api garmin login
+```
+
+This is the only place a password is ever typed. It asks for your Garmin email, password and any
+multi-factor code, then stores tokens in `~/.garmin-api/default`, readable by your user only.
+Nothing else ever prompts for a password; without tokens, every tool says to run this.
+
+**2. Add the server to your MCP client.**
+
+Claude Code:
+
+```bash
+claude mcp add --scope user --transport stdio garmin -- uvx garmin-connect-api
+```
+
+Claude Desktop, in `claude_desktop_config.json` (in `~/Library/Application Support/Claude/` on
+macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "garmin": {
+      "command": "uvx",
+      "args": ["garmin-connect-api"]
+    }
+  }
+}
+```
+
+**3. Ask.** "How did I sleep this week?", "Did my pace hold up in yesterday's swim?",
+"How has my resting heart rate moved since summer?", "Show my last strength session's sets, and
+change sets 3 to 5 to dumbbell rows", "Schedule a swim for Thursday: 200 easy, then 8 x 100 free
+on 20 seconds rest, in a 25-yard pool".
+
+## What it can do
+
+41 tools, each annotated so your client knows which only read (27), which add something (8) and
+which delete or overwrite (6), and can ask before running those.
+
+| Read | Write |
+| --- | --- |
+| Activities, filtered by type and date | Create a strength workout, schedule it, push it to a watch |
+| Per-set strength detail: exercise, reps, weight | Create a run, ride or pool swim workout, with targets |
+| Laps for runs and rides; pace per 100 for pool swims | Log a completed strength session, with every set |
+| A day in one answer: steps, heart rate, stress, body battery, sleep, HRV, readiness | Correct a session's sets: exercise, reps, weight |
+| Trends over up to two years: twelve metrics, daily, weekly or monthly | Record a weigh-in, or a full body composition reading |
+| Personal records, named and in units | Rename an activity or change its description |
+| Every weigh-in with body composition | Delete an activity, workout or weigh-in |
+| Planned workouts and the calendar | |
+| Garmin's 1,527-exercise catalogue, offline | |
+
+Four tools are written for a model rather than mirrored from an endpoint: `garmin_status` checks
+the login without calling Garmin, `find_exercise` finds Garmin's name for a lift, and
+`recent_strength_sessions` and `week_summary` answer common questions in one call.
+
+**Logging a finished workout** is the write Garmin's own developer programme has never offered. A
+session is encoded as a FIT activity file with set messages and uploaded, so it appears in Garmin
+Connect as a Strength Training activity, exercise by exercise.
+
+**Body composition** from a smart scale (fat, water, skeletal muscle, bone, BMI, basal metabolic
+rate, visceral fat) is written as a FIT weight-scale file, the way Garmin's own Index scales do it.
+A plain weigh-in carries weight alone.
+
+## Example output
+
+Answers come back compact, summarised the way a person would read them. These are from made-up
+data in the shapes Garmin returns.
+
+"Did my pace hold up in yesterday's swim?" calls `get_activity_laps`:
+
+```json
+{
+  "sport": "lap_swimming",
+  "pool_length": 25.0,
+  "pool_unit": "m",
+  "summary": {
+    "lengths": 80,
+    "distance": 2000.0,
+    "average_pace": "1:52/100m",
+    "first_half_pace": "1:50/100m",
+    "second_half_pace": "1:54/100m",
+    "by_stroke": {"FREESTYLE": 1800.0, "BACKSTROKE": 200.0},
+    "fastest_segment": {"lengths": "5-8", "pace": "1:44/100m"},
+    "slowest_segment": {"lengths": "77-80", "pace": "2:01/100m"}
+  }
+}
+```
+
+"How has my resting heart rate moved since summer?" calls `get_trend`, which rolls a long range
+into weeks:
+
+```json
+{
+  "metric": "resting_hr",
+  "unit": "bpm",
+  "aggregation": "week",
+  "summary": {
+    "days_with_data": 88,
+    "average": 54.2,
+    "min": 49.0,
+    "max": 61.0,
+    "first_period_average": 57.3,
+    "last_period_average": 51.6,
+    "change": -6.0
+  }
+}
+```
+
+## Before you write anything
+
+- **Activities you log may be shared automatically.** If your Garmin account is connected to Strava
+  or another app, an uploaded session can be posted there too, and deleting it from Garmin does not
+  delete it there.
+- **Rate limits are taken seriously.** Garmin puts Cloudflare and per-account rate limits in front
+  of its login, and a run of failed logins can lock an account out for a day or more. Nothing here
+  retries a login, and a rate limit stops every call path rather than being retried. If you see
+  one, wait.
+- **Exercises need Garmin's own names**, such as `BENCH_PRESS` / `BARBELL_BENCH_PRESS`. Every write
+  checks them against the catalogue first and suggests near misses, so a typo fails with a useful
+  message rather than Garmin's bare 400. Common gym names work in search: "rdl", "ohp", "pull ups".
+- **Sessions and body-composition readings need a timezone offset**, or a 7am reading would land
+  hours out. They are refused without one.
+
+## Command line
+
+```bash
+garmin doctor                          # setup check, no network
+garmin activities --type strength_training --limit 5
+garmin sets <activity-id>              # per-set detail
+garmin day 2026-10-18                  # one day of health data
+garmin exercises "lat pulldown"        # search the catalogue, offline
+garmin workout create workout.json     # plan a strength workout
+garmin log-session session.json        # log a completed one
+garmin encode-session session.json     # build its FIT file without uploading
+garmin decode-fit activity.zip         # read sets out of a Garmin export
+garmin serve                           # the HTTP API on 127.0.0.1:8765
+```
+
+Run them with `uvx --from garmin-connect-api garmin ...`, or install with
+`uv tool install garmin-connect-api`. Example specs:
+[session.json](https://github.com/happyc0der/garmin-connect-api/blob/main/examples/session.json),
+[workout.json](https://github.com/happyc0der/garmin-connect-api/blob/main/examples/workout.json).
+
+An encoded session file can also be imported by hand on the Garmin Connect website, if you would
+rather nothing logged in on your behalf.
+
+## Python library
+
+```python
+from datetime import datetime, timedelta, timezone
+from garmin_api.services import activities, health, uploads
+from garmin_api.models.workouts import (
+    StrengthSessionSpec, StrengthSessionExercise, StrengthSessionSet,
+)
+
+for activity in activities.list_activities(limit=5, activity_type="strength_training"):
+    sets = activities.get_sets(activity.activity_id)
+    print(activity.name, sets.total_volume_kg, "kg")
+
+print(health.day("2026-10-18").steps)
+
+uploads.log_strength_session(StrengthSessionSpec(
+    name="Push A",
+    start_time=datetime(2026, 10, 18, 7, 0, tzinfo=timezone(timedelta(hours=-4))),
+    exercises=[StrengthSessionExercise(
+        category="BENCH_PRESS",
+        exercise_name="BARBELL_BENCH_PRESS",
+        sets=[StrengthSessionSet(reps=10, weight_kg=60.0, rest_s=120)],
+    )],
+))
+```
+
+Responses are pydantic models with Garmin's inconsistencies ironed out: kilograms rather than
+grams, timezone-aware instants, snake_case throughout. Garmin's own payload is still on `raw` when
+something is not mapped.
+
+## HTTP API
+
+`garmin serve` runs the same API on `127.0.0.1:8765`, with interactive docs at `/docs`. The MCP
+tools are generated from these routes, so the two cannot drift apart. Because it can write to your
+account, the service refuses writes from web pages open in your browser and requests naming any
+host but `localhost`, which defeats DNS rebinding. Binding beyond localhost requires
+`GARMIN_API_KEY`.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `GARMINTOKENS` | Where tokens are stored. Defaults to `~/.garmin-api/default`. |
+| `GARMIN_API_KEY` | Required to bind the HTTP service beyond localhost. |
+| `GARMIN_API_HOSTS` | Extra host names the HTTP service answers to, comma-separated. |
+
+## Development
+
+```bash
+git clone https://github.com/happyc0der/garmin-connect-api
+cd garmin-connect-api
+uv sync
+uv run pytest
+```
+
+231 offline tests, needing no network and no account, run on Linux, macOS and Windows. They cover the models against real Garmin
+response shapes, the FIT codec's round trip, every one of the 1,527 catalogue exercises against
+the FIT profile, the HTTP routes, and every MCP tool's output against its own advertised schema,
+which strict clients enforce.
+
+Tests against a real account are opt-in, and the ones that create data need a second opt-in:
+
+```bash
+GARMIN_LIVE=1 uv run pytest tests/live                      # read only
+GARMIN_LIVE=1 GARMIN_LIVE_WRITE=1 uv run pytest tests/live  # creates, then deletes
+```
+
+## Why the unofficial route
+
+Garmin's official Connect Developer Program is for businesses, has no endpoint that uploads a
+completed activity, and was closed to new applicants in 2026. The aggregators that wrap it cost
+hundreds of dollars a month and are read-only or plans-only. So this uses the endpoints Garmin's
+own website uses, gently: no polling, no retries on a rate limit.
+
+## Citing
+
+If you use this in research, cite it with the metadata in [CITATION.cff](https://github.com/happyc0der/garmin-connect-api/blob/main/CITATION.cff);
+GitHub's "Cite this repository" button formats it.
+
+## Licence
+
+MIT. Garmin and Garmin Connect are trademarks of Garmin Ltd., used here only to say what this
+works with.

garmin_connect_api-0.2.0/SECURITY.md

@@ -0,0 +1,12 @@
+# Security
+
+This package holds tokens that can read and change a Garmin Connect account, so please report
+security problems privately rather than in a public issue: use GitHub's
+[private vulnerability reporting](https://github.com/happyc0der/garmin-connect-api/security/advisories/new).
+
+What is in scope: anything that could expose stored tokens, let something other than the owner
+reach the local HTTP service or the MCP server's write tools, or write to Garmin without the
+owner asking.
+
+Tokens live in `~/.garmin-api/default` (or `GARMINTOKENS`), readable by your user only. If you
+think they have leaked, run `garmin logout` and then `garmin login` to replace them.

garmin_connect_api-0.2.0/examples/session.json

@@ -0,0 +1,23 @@
+{
+  "name": "Push A",
+  "start_time": "2026-09-21T07:00:00+02:00",
+  "exercises": [
+    {
+      "category": "BENCH_PRESS",
+      "exercise_name": "BARBELL_BENCH_PRESS",
+      "sets": [
+        { "reps": 10, "weight_kg": 60.0, "rest_s": 120 },
+        { "reps": 8, "weight_kg": 65.0, "rest_s": 120 },
+        { "reps": 6, "weight_kg": 70.0, "rest_s": 120 }
+      ]
+    },
+    {
+      "category": "SHOULDER_PRESS",
+      "exercise_name": "DUMBBELL_SHOULDER_PRESS",
+      "sets": [
+        { "reps": 12, "weight_kg": 20.0, "rest_s": 90 },
+        { "reps": 12, "weight_kg": 20.0, "rest_s": 90 }
+      ]
+    }
+  ]
+}