DEV Community: Ivan Ficko

Connect your Garmin to Claude in two minutes

Ivan Ficko — Mon, 26 Oct 2026 12:20:33 +0000

No coding needed. If you're a developer who wants Garmin data in your own app, see Build with Garmin data instead.

If you wear a Garmin watch, you have months or years of data about your sleep, heart rate, recovery and training sitting in the Garmin Connect app. It's all there, but asking it a simple question, like "Am I sleeping worse since I started marathon training?", means a lot of tapping through charts.

This series is about asking that question in plain words instead, using Claude and a free Garmin connector I built. You don't need to be a programmer, and there's nothing to install.

In this first part:

Adding the connector (about two minutes)
What it can see, what it stores, and how to remove it
The first five questions to ask

A real answer from the connector. The numbers have been changed for privacy.

What you need

A Garmin Connect account. If you use a Garmin watch, you have one.
A Claude account at claude.ai. The connector works in Claude on the web, in the Claude phone apps and in Claude Desktop.

A quick but important note: this connector is unofficial. It isn't made by Garmin or by Anthropic. It's open source, and it talks to Garmin the same way the Garmin Connect app does.

Step 1: add the connector

You add it once on the web, and it then follows your Claude account to your phone and computer.

1. Go to claude.ai and click Customize in the left sidebar, then Connectors.

2. Click Add at the top right, then Add custom connector.

3. Name it Garmin, and paste this address into MCP server URL:

https://garmin.ficdev.xyz/mcp

4. Click Continue.

If you don't see Add custom connector, custom connectors may not be available on your Claude plan, or your organisation's admin may have turned them off. Claude's help center lists which plans include them.

Step 2: sign in to Garmin

A Garmin sign-in window opens. Enter the email and password you use for Garmin Connect.

Two-factor codes work. If Garmin sends you a code by email or text, the window asks for it next.
It takes a few seconds. Garmin's sign-in has several steps behind the scenes, so a short wait after you press the button is normal.

When you've signed in, the window sends you back to Claude, and the connector shows a tick in your list:

Using the Claude phone app? You don't need to do anything there. Once the connector is on your account, the app picks it up automatically. The same goes for Claude Desktop.

Step 3: ask your first question

Start a new chat and ask:

How did I sleep this week compared with last week?

Claude works out which Garmin data it needs, fetches it and answers. Above the answer you'll see a small line like "used Garmin MCP integration". Click it to see exactly what it did: here it looked up the right tool, then called getSleepDaily for the two weeks.

This is worth a look now and then. It shows you which dates Claude actually asked for, so you can tell a careful answer from a guess.

The first time, Claude may ask your permission to use the connector. You can allow it once, or always.

Five good first questions

"How did I sleep this week compared with last week?"
"What has my HRV done over the last month? Anything unusual?"
"Am I ready to train hard today?"
"What were my last five runs? Compare their pace and average heart rate."
"What do my race predictions say, and how have they changed since the summer?"

Plain questions work best. You don't need to know what any of the Garmin data is called. Follow-up questions work too: "Why do you think Tuesday was so bad?"

What it can see and store

This is your health data, so here's exactly what happens to it.

What Claude can do. Through the connector, Claude can read your Garmin data, and it can also save some things for you: workouts, weigh-ins, and changes like renaming an activity. Anything that deletes or overwrites data is marked as destructive, so Claude asks you before doing it. You'll see the workout features in Part 3.

What the connector stores.

Your password goes to Garmin once, at sign-in, and is never stored.
Your Garmin session isn't stored on the server either. It's encrypted inside the connection token that your Claude account keeps.
The server keeps one small record per connection: a random id, a scrambled reference to your Garmin account, the app's name (for example "Claude"), and timestamps. It's deleted after 35 days without use.
Your Garmin data passes through to Claude and isn't kept.

What Claude sees. The data the connector fetches becomes part of your conversation, the same as anything you paste into a chat. How Claude handles conversations is covered by Anthropic's privacy policy.

The connector's full privacy policy states all of this as facts about the code, which is open source.

Removing it

Either of these disconnects it:

In Claude, go to Customize → Connectors and remove Garmin.
Or, the next time you sign in to Garmin through the connector, tick "Disconnect my other Garmin connections".

To end the session on Garmin's side as well, change your Garmin password.

If something doesn't work

"Sign-in failed" or "too many attempts." Garmin limits how often you can sign in. Wait 15 minutes and try again. You only need to sign in once; after that the connection keeps itself alive as long as you use it at least once a month.

Saving fails, but reading works (European accounts). If you're in the EU and Claude says Garmin refused to save something, your Garmin account hasn't granted upload consent yet. It's a one-time setting in your Garmin Connect account's privacy settings, and Garmin requires it for every app that saves data to your account. Grant it there, then try again.

Claude says there's no data. It can only see what your watch recorded and synced to Garmin Connect. A night you didn't wear the watch, or a feature your watch doesn't have (some don't measure HRV), shows up as no data.

Claude didn't use Garmin at all. Start your question with "From my Garmin data, …", or check that the connector is switched on in the chat's tools menu.

What's next

In Part 2 we'll go deeper on asking questions: comparing weeks and months, checking whether you're recovering well, reading race predictions sensibly, and how to tell when Claude's answer is solid and when it's guessing.

Set-up guides for every Claude app: garmin.ficdev.xyz/claude
How it's built (for the curious): my first post

What was the first thing you asked? Tell me in the comments. I collect good questions for the next post.

From zero to your first Garmin data in Node

Ivan Ficko — Mon, 26 Oct 2026 12:18:36 +0000

For developers. Just want to ask Claude about your training, with no code? Start with Your Garmin data in Claude instead.

In my first post I introduced garminconnect-js, a typed, zero-dependency Garmin Connect client for Node. This series is the hands-on version: four posts that take you from an empty folder to an app that reads and writes Garmin data.

This first part covers the foundation everything else stands on:

Signing in, including two-factor (MFA) codes
Keeping the session, so you sign in once and not on every run
Reading data, and what "no data" looks like
Handling errors properly

By the end you'll have a small command-line script that prints last night's sleep and HRV.

Written against garminconnect-js 0.10.0. Every snippet here type-checks against that version.

What you need

Node 18 or newer (node --version)
A Garmin Connect account with some data in it. A watch that records sleep makes this post more fun, but everything works without one.

A quick note on what this library is: Garmin has no public API for your own Connect data, so garminconnect-js talks to the same endpoints Garmin's web and mobile apps use. It's unofficial, those endpoints can change, and it's server-side only. Your Garmin password and tokens should never reach a browser.

Set up the project

mkdir garmin-sleep && cd garmin-sleep
npm init -y
npm install garminconnect-js
npm install -D tsx typescript @types/node

On Deno or Bun, the same code is published on JSR as @dynamicsninja/garminconnect (npx jsr add @dynamicsninja/garminconnect).

tsx runs TypeScript files directly, so there's no build step for a script like this. Add "type": "module" to package.json so top-level await works:

{
  "type": "module"
}

And keep your secrets out of git from the start:

echo "tokens/" >> .gitignore
echo ".env" >> .gitignore

Step 1: sign in once

Create login.ts:

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { GarminClient, FileTokenStore } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });

const result = await client.login(process.env.GARMIN_EMAIL!, process.env.GARMIN_PASSWORD!);

if (result.state === "mfa_required") {
  const rl = createInterface({ input: stdin, output: stdout });
  const code = await rl.question("Garmin sent you a code. Enter it: ");
  rl.close();
  await client.resumeLogin(result.mfaState, code.trim());
}

console.log("Signed in. Your session is saved in ./tokens");

Run it with your credentials in the environment:

GARMIN_EMAIL=you@example.com GARMIN_PASSWORD='...' npx tsx login.ts

(On Windows PowerShell, set them first with $env:GARMIN_EMAIL="you@example.com", or use a .env file and node --env-file=.env --import tsx login.ts.)

If you use a .env file and your password contains a #, put the value in quotes: GARMIN_PASSWORD="...". Without them, Node reads everything from the # on as a comment, Garmin gets a shortened password, and you get a GarminAuthError that looks like a wrong password. It happened to me while testing this post.

Three things are worth understanding here.

login() doesn't throw or block on MFA. If your account has two-factor turned on, it returns { state: "mfa_required", mfaState } and you finish with resumeLogin(mfaState, code). In a script, that's a prompt. In a web app, the two halves can happen in two separate HTTP requests, which is exactly what Part 2 builds on.

FileTokenStore keeps your session on disk. After a successful login, the library writes two small JSON files to ./tokens. Those files are your Garmin session, so treat them like a password: keep them out of git, and off any machine you don't trust.

Sign in as rarely as possible. Garmin rate-limits sign-ins, sometimes after only one or two attempts in a row. The library already falls back to Garmin's web sign-in when the mobile one is rate-limited, but the real fix is not to sign in repeatedly. Sign in once, then reuse the tokens.

Step 2: reuse the session

Every other script starts like this instead:

import { GarminClient, Garmin, FileTokenStore } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });

if (!(await client.loadTokens())) {
  console.error("Not signed in yet. Run login.ts first.");
  process.exit(1);
}

const garmin = new Garmin(client);

loadTokens() returns false rather than throwing when there's nothing saved, so the "not signed in" case is just an if.

You never refresh tokens yourself. The short-lived access token lasts about a day, and the library renews it automatically before any request that needs it, then saves the new one back through your token store. The underlying session keeps rolling forward as long as you make a call at least once every 30 days. Go longer than that and you'll get a GarminAuthError, which means "sign in again".

Garmin is the class with all the methods (about 200 of them). Create one per signed-in user and reuse it: it caches your profile, which most date-based calls need.

Step 3: read last night's sleep

Here's the full script, sleep.ts:

import { GarminClient, Garmin, FileTokenStore, GarminAuthError, GarminError } from "garminconnect-js";
import type { PersonalApi } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
if (!(await client.loadTokens())) {
  console.error("Not signed in yet. Run login.ts first.");
  process.exit(1);
}
const garmin = new Garmin(client);

// Garmin files a night's sleep under the date you woke up.
const date = process.argv[2] ?? new Date().toISOString().slice(0, 10);

const hours = (seconds?: number | null) =>
  seconds == null ? "?" : `${Math.floor(seconds / 3600)}h ${Math.round((seconds % 3600) / 60)}m`;

try {
  const [sleep, hrv] = await Promise.all([garmin.getSleepData(date), garmin.getHrvData(date)]);

  const night = sleep?.dailySleepDTO as PersonalApi.DailySleepDTO | undefined;
  if (!night?.sleepTimeSeconds) {
    console.log(`No sleep recorded for ${date}.`);
  } else {
    console.log(`Sleep on ${date}: ${hours(night.sleepTimeSeconds)}`);
    console.log(`  Score: ${night.sleepScores?.overall?.value ?? "n/a"}`);
    console.log(`  Deep ${hours(night.deepSleepSeconds)}, REM ${hours(night.remSleepSeconds)}`);
  }

  const summary = hrv?.hrvSummary;
  if (summary) {
    console.log(`HRV: ${summary.lastNightAvg ?? "?"} ms last night, ${summary.weeklyAvg ?? "?"} ms weekly average (${summary.status ?? "no status"})`);
  }
} catch (error) {
  if (error instanceof GarminAuthError) {
    console.error("Your Garmin session has expired. Run login.ts again.");
  } else if (error instanceof GarminError) {
    console.error(`Garmin error: ${error.message}`);
  } else {
    throw error;
  }
  process.exit(1);
}

Run it for today, or for any date:

npx tsx sleep.ts
npx tsx sleep.ts 2026-10-20

The output looks like this (your numbers will differ):

Sleep on 2026-10-20: 7h 34m
  Score: 81
  Deep 1h 22m, REM 1h 51m
HRV: 52 ms last night, 49 ms weekly average (BALANCED)

"No data" is not an error

Notice the checks for null and undefined. For most Garmin endpoints, an empty answer is normal: no watch worn that night, no HRV feature on your device, or simply a date before you owned the watch. getSleepData and getHrvData return null in that case; they don't throw.

A few methods do throw on an empty answer, for example getActivity when the id doesn't exist. The library's reference says which is which, method by method, so check there rather than assuming one rule for all.

Dates are UTC calendar dates

Every method takes a date either as "YYYY-MM-DD" or as a Date. A Date is converted with toISOString(), which is UTC. If you're in New York and pass new Date() at 9 p.m., you're asking for tomorrow. When the day matters, pass the string you mean.

Typed, but honest about it

Most responses have real types. Many are generated from Garmin's own Personal API spec and exported as PersonalApi.*, which is where DailySleepDTO above comes from. A few raw responses are deliberately loose (Record<string, unknown>) because Garmin's shape varies too much to promise more. That's why the script narrows dailySleepDTO to the spec's type in one place.

Handling errors

Every error the library throws is a GarminError or a subclass, so you can handle them by type:

Error	Means	What to do
`GarminAuthError`	The session is gone or invalid (401/403, expired tokens)	Sign in again
`GarminRateLimitError`	Garmin said 429	Back off. It carries `retryAfter` (seconds) when Garmin sends one
`GarminConnectionError`	Network failure or timeout, after retries	Retry later, but read the note below
`GarminHttpError`	Any other non-2xx	Inspect `status` and `body`

The library already retries GET requests on network errors and 5xx responses, with backoff. It never retries a POST, so a write can't be duplicated behind your back.

One trap: a few permanent errors are deliberately reported as GarminConnectionError, such as uploading an activity that already exists. So never write a blind catch (e) { if (e instanceof GarminConnectionError) retryForever() }. Look at the message, or at error.cause, first.

Beyond sleep

The same pattern, sign in once and then call methods, covers the rest of your data. A few to try in the same script:

await garmin.getUserSummary(date);            // steps, calories, stress, Body Battery for one day
await garmin.getDailySummaries("2026-10-01", "2026-10-20"); // the same, one row per day, for a range
await garmin.getTrainingReadiness(date);      // readiness score and what's driving it
await garmin.getRacePredictions();            // 5K, 10K, half and full marathon predictions
await garmin.getActivities(0, 5);             // your five most recent activities

And if you need an endpoint the library doesn't wrap, client.connectapi(path) calls any Garmin Connect path with the same authentication. You'll see that in Part 4.

What's next

You now have the two building blocks: a session you sign in to once, and typed reads with proper error handling. In Part 2 we'll put this behind a web app: a Next.js app where users sign in with their own Garmin account (MFA included, across two requests), with tokens stored in your database instead of a folder.

Docs and every method: garmin.ficdev.xyz
Source (MIT): github.com/DynamicsNinja/garminconnect-js

If something here doesn't match what your account returns, tell me in the comments. Undocumented endpoints are full of surprises, and every report makes the library better.

I gave Claude access to my Garmin data: a free MCP server and TypeScript library

Ivan Ficko — Fri, 23 Oct 2026 15:29:38 +0000

I wear a Garmin watch every day, and for a long time my data lived in one place: the Garmin Connect app. I wanted it in my own code, and lately I wanted to ask an AI about it: "How did I sleep this week?", "Am I ready for intervals today?", "Build me a 6x400 session and put it on my watch."

Garmin has no public API for personal Connect data, so I built two things:

garminconnect-js, a TypeScript client for Garmin Connect with 200 typed methods and zero runtime dependencies.
A Garmin MCP server on top of it, so Claude (or any MCP client) can read and manage your Garmin data in plain language.

Everything is free and open source, and the home for both is garmin.ficdev.xyz.

Try it in a minute: add https://garmin.ficdev.xyz/mcp as a custom connector in Claude, then ask how you slept this week.

Part 1: Garmin in Claude, in about a minute

If you just want to talk to your training data, you don't need to install anything. A hosted copy of the MCP server runs at:

https://garmin.ficdev.xyz/mcp

claude.ai (web, Desktop and the phone apps): Settings, Connectors, Add custom connector. Paste the URL, sign in to Garmin in the window that opens (with your MFA code if you use one), and you're done. It follows your account to Claude Desktop and mobile.

Claude Code:

claude mcp add --transport http garmin https://garmin.ficdev.xyz/mcp

Any other MCP client: add a streamable-HTTP server with that URL.

The hosted server never stores your Garmin tokens. They're sealed inside the OAuth token your MCP client holds, so the server keeps no copy of them. If you'd rather run everything locally, there's a one-click Claude Desktop Extension (.mcpb) on the releases page and an npm package, @dynamicsninja/garminconnect-mcp.

What you can ask

Plain questions work. Claude picks the tools and shows you which ones it used:

"How did I sleep this week compared with last week?"
"What has my HRV done over the last month?"
"Am I ready to train hard today?"
"Find my runs over 10 km since June, longest first, and compare their average heart rate."
"What are my race predictions?"
"Log 72.4 kg for this morning."

And the one I built it for:

"Make me a 6x400 m session at 5k pace with 2-minute jog recoveries, put it on Thursday, and send it to my watch."

Claude previews the workout in readable form (steps, targets, paces in /km and /mi) and saves nothing until you confirm. Then it saves it to your workout library, schedules it, and pushes it to your device. Strength, swim, HIIT, yoga, pilates, mobility, cycling and multi-sport work too, and exercise names are checked against Garmin's catalogue so a typo can't slip through.

Tools that delete or overwrite data (activities, workouts, gear, weigh-ins) are marked destructive, so Claude asks you first.

Part 2: Garmin in your code

npm install garminconnect-js

import { GarminClient, Garmin, FileTokenStore } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
const result = await client.login(process.env.GARMIN_EMAIL!, process.env.GARMIN_PASSWORD!);

if (result.state === "mfa_required") {
  await client.resumeLogin(result.mfaState, await promptForCode());
}

const garmin = new Garmin(client);
const sleep = await garmin.getSleepData("2026-10-22");
const hrv = await garmin.getHrvData("2026-10-22");

What you get:

Garmin's SSO and OAuth flow handled for you, including MFA. login() doesn't block on MFA. It returns a plain-JSON state you can carry across two HTTP requests, which is what you need in a serverless Next.js route.
Automatic token refresh. Sessions roll forward as long as you make a call at least once every 30 days. Tokens go wherever you want: memory, disk, or your own database through a three-method TokenStore interface.
200 typed methods: sleep, HRV, stress, Body Battery, daily summaries, activities (list, search, details, splits, download, upload), training readiness and status, race predictions, workouts, gear, courses, calendar events, devices, badges, weigh-ins, women's health, golf, nutrition and training plans.
An escape hatch. client.connectapi(path) calls any Garmin Connect endpoint with the same auth, for the rare thing the library doesn't wrap.
Zero runtime dependencies, Node 18+. It's server-only on purpose: your Garmin credentials should never reach a browser.

Want a running app first? The Next.js starter template signs in (MFA included) and charts your sleep and HRV, and there's a live demo.

The workout builder, or: Garmin's API is quietly hostile

Writing workouts was the hardest part, because Garmin's workout JSON has traps that don't fail loudly. They succeed and store the wrong thing:

stepOrder is global. Steps inside a repeat block don't restart at 1. They continue the outer sequence. Number them per block and the upload is rejected; number them per segment in a multi-sport workout and it's rejected again.
Pace targets are speeds in metres per second, fastest first. Send "4:00 to 4:12 min/km" the obvious way and Garmin happily stores a nonsense target.
A rest in seconds isn't a time step. It's a different end condition entirely.
Every sport, step and condition is an id/key pair that must agree.

So the library has a fluent builder that makes all four unreachable:

import { buildWorkout } from "garminconnect-js";

const workout = buildWorkout("6x400", { sport: "running" })
  .warmup({ lapButton: true })
  .repeat(6, (set) =>
    set
      .interval({ distance: 400, target: { pace: { minPerKm: [4, 4.2] } } })
      .recovery({ time: 120 }),
  )
  .cooldown({ time: 600 })
  .build();

await garmin.uploadWorkout(workout);

The pace converts to descending m/s for you, step orders are counted across the whole tree, and the sport/step ids come from Garmin's own enums.

Exercise names fail silently, so they're type-checked

My favourite trap: if you send a strength exercise name Garmin doesn't recognise, it stores an empty string and returns success. Your "Barbell Back Squat" quietly becomes a blank step on your watch.

So garminconnect-js/exercises ships Garmin's catalogue as types: 1,830 names across 51 categories, every one uploaded to a live account and kept only if Garmin echoed it back unchanged. Once you pick a category, name autocompletes to that category's exercises, and anything else is a compile error:

buildWorkout("Legs", { sport: "strength_training" })
  .interval({ reps: 8, exercise: { category: "SQUAT", name: "BARBELL_BACK_SQUAT" } })
  .interval({ reps: 8, exercise: { category: "SQUAT", name: "BARBELL_BENCH_PRESS" } }); // tsc error

It lives in a separate entry point, so the root bundle doesn't carry the catalogue.

For input that can't hold callbacks (a database row, a form, an LLM tool call), workoutFromSpec takes the same workout as plain JSON and comes with a JSON Schema. That's exactly what the MCP server hands to Claude, and when Claude gets something wrong, the error comes back with the JSON path and the closest valid exercise names, so it can fix its own mistake.

"Verified" means I read it back

Since the endpoints are undocumented, a passing test suite against mocks proves very little. A mock written from an assumption agrees with the code written from the same assumption. Three real bugs shipped that way early on, including one that stored a 93 kg weigh-in as 93,000 kg.

So every method carries a live-verification note, and a write only counts as verified once the stored value has been read back. A 2xx on its own has hidden real defects more than once:

A "walking workout" helper got a 2xx from Garmin every time. Reading it back showed the workout was stored with no sport at all, because Garmin has no walking workout type. The helper was removed.
Pushing a workout to a watch was declared to return a workout. The first time it ran against a real device, it returned an array of device messages.
Goal lists are 1-indexed, and start=0 returns [] with no error, indistinguishable from "you have no goals".
Perceived effort (RPE) is stored times ten.

All of these are written down in AGENTS.md, which doubles as a briefing for AI coding agents, so Copilot or Claude Code doesn't confidently invent a method that doesn't exist.

How the MCP server stays in sync

The MCP server holds no Garmin knowledge of its own. A script reads the library's source with the TypeScript compiler and generates a manifest of every method: parameters as JSON Schema, plus a safety class (read, write or destructive). Each tool is generated from that manifest, so when a method is added to the library, the tool appears in Claude after the next build, already annotated. Arguments are validated against the schema before any request reaches Garmin.

The fine print

This is unofficial and not affiliated with Garmin. It uses the same undocumented endpoints as the Garmin Connect web and mobile apps, so Garmin can change them at any time. Don't build anything safety-critical on it. One gotcha worth knowing up front: on an EU account, every write returns a 412 until you've granted upload consent in Garmin Connect's settings.

Try it

Talk to your data in Claude: add https://garmin.ficdev.xyz/mcp as a custom connector
Use it in code: npm install garminconnect-js
Docs, setup for every client, and the demo: garmin.ficdev.xyz
Source (MIT, a star helps): github.com/DynamicsNinja/garminconnect-js

If you build something with it, or find an endpoint that behaves differently on your account, I'd love to hear about it in the comments or in a GitHub issue. And if you try the connector, tell me the most useful question you asked Claude about your training.