Skip to content

xichen-de/garmin-owl

v0.4.0MIT

Local, read-only access to Garmin health and training data.

garmin-owl

Ask Claude (or ChatGPT) about your Garmin data: sleep, HRV, recovery, workouts, training load, and long-term trends.

  • Private: runs on your computer. There is no server or account in between.
  • Read-only: it can't change anything in your Garmin account.
  • Honest: when Garmin has no value, it says so instead of guessing.

Works on macOS and Ubuntu Linux.

What you need

Setup

1. Sign in to Garmin

Run this once in a terminal:

git clone https://github.com/xichen-de/garmin-owl.git
cd garmin-owl
uv sync --locked
uv run garmin-owl-auth

Enter your Garmin email, password and MFA code. Your password isn't saved, only a session token in ~/.garminconnect. Keep that folder private.

2. Install the extension

  1. Download the latest .mcpb file from Releases.
  2. Drag it into Claude Desktop → Settings → Extensions, then enable it.
  3. Start a new chat.

Using ChatGPT? Follow docs/chatgpt.md instead.

3. Ask

  • "Summarize my recovery today."
  • "How did I sleep last night?"
  • "Compare my last two runs."
  • "How have my resting HR and HRV changed month by month over the last year?"
  • "Show my VO2 max since I got my watch."

What it can answer

  • Any day: sleep, HRV, resting HR, stress, Body Battery, training readiness, cycle phase
  • Workouts: activity lists, details with your own notes and effort ratings, comparisons, weekly totals
  • One workout in depth (only when you ask about that workout): per-sample HR, pace, cadence, elevation, and respiration charts, climb-by-climb HR response, and the same hill compared across days, all without GPS
  • Training: load and status, zones, running tolerance, VO2 max
  • Long-term: daily history or monthly summaries over up to three years, and when your data starts

See the full tool list and limits.

Add your own context (optional)

Trends often depend on things Garmin doesn't know about. Write them in ~/.garmin-owl/events.toml:

[[event]]
date = 2026-03-01
end_date = 2026-06-30    # optional
label = "Started new medication"

[[event]]
date = 2026-01-12
label = "Flu"

Long-range answers include the events from the period they cover. garmin-owl only reads this file.

Updating

Download the new .mcpb from Releases and drag it in again. Then run git pull in your garmin-owl folder. Your sign-in and cached data carry over.

If something goes wrong

Check sign-in and the main reads (this shows pass/fail only, never your data):

uv run garmin-owl-smoke
  • "authentication expired" or "No local Garmin tokens": run uv run garmin-owl-auth again.
  • "rate limit reached": wait a few minutes and ask again.
  • Extension not showing: restart Claude Desktop.

Anything else: see Troubleshooting.

Privacy

  • Your data goes only from Garmin to your computer and into your chat. There is no telemetry and no remote database.
  • garmin-owl keeps a local cache so each day is fetched only once (details).
  • Whatever reaches your chat is handled under your Claude or ChatGPT privacy settings.
  • This is not medical advice.

garmin-owl uses the unofficial python-garminconnect client, so a change on Garmin's side can occasionally break a read until garmin-owl is updated.

Uninstall

Remove the extension in Claude Desktop, then delete your garmin-owl folder. To also remove your data, delete the cache (~/Library/Application Support/garmin-owl on macOS, ~/.local/share/garmin-owl on Linux) and ~/.garmin-owl. Delete ~/.garminconnect only if no other Garmin tool uses it.


Developing garmin-owl? See CONTRIBUTING.md.