DEV Community

Shalom Yerushalmy
Shalom Yerushalmy

Posted on Originally published at blog.yershalom.com

Talk to your Garmin data in Claude, for free

I wanted to get healthier, and I wanted a coach I could ask "how did this week actually go?" without scrolling through five screens of the Garmin app. So I connected my watch to Claude. Here's what I built, what it taught me about my own habits, and how you can set up your own copy in about 15 minutes for $0.

What I wanted

My plan was simple: two long walks and two gym sessions a week, more sleep, and steady progress instead of big heroic weeks followed by nothing. The data was already on my wrist. What I didn't have was an easy way to ask questions of it:

  • Did my walks actually stay in the heart-rate zone I was aiming for?
  • Am I sleeping as badly as I feel, or is it just one night?
  • Should I push today, or is my body still recovering?

Claude can answer those questions in plain language, if it can read the data. That's what an MCP server is for: a small service that gives Claude a set of tools, like "get my sleep for these dates", that it can call when you ask something.

What I got out of it

A week in, these were the useful bits. None of them needed a dashboard, only a question:

  • A weekly check-in that takes one sentence. "Check my week against my plan" gets back what I did, what I missed, and how to fit the rest in, without me counting anything.
  • Honest pace feedback. Some of my walks felt hard but sat below my target heart-rate zone. Now I know to walk a bit faster, not longer.
  • My sleep data was there all along. Another app I use showed big gaps in my nights. Garmin had every night. The gaps were a sync problem, not my sleep, and I'd never have spotted that by looking at one app.
  • Knowing when to back off. After a long flight, Body Battery and resting heart rate showed I hadn't recovered. Claude suggested a lighter gym session instead of skipping it or overdoing it. That's the kind of call I usually get wrong.
  • Gym sessions that count. When I start a strength workout on the watch, the sets and reps come through too, so progress is visible from week to week.

How it works

Claude ──OAuth token──▶ Your Worker (/mcp, Cloudflare) ──Bearer token──▶ Garmin Personal API
  (signs in once with           │
   GitHub, only you)            └─ KV: grants + cached Garmin token
Enter fullscreen mode Exit fullscreen mode

Claude never sees your Garmin key. The Worker holds it and only answers Claude after you've signed in.

  • Garmin's Personal API is official and read-only. You create a personal API key in Garmin Connect, and the server swaps it for an access token that lasts 24 hours. No scraping, and no sharing your Garmin password.
  • A Cloudflare Worker keeps the key as a secret, caches the token in KV, refreshes it before it expires, and exposes about 20 read-only tools: daily summaries, sleep, heart rate, HRV, Body Battery, stress, weight, VO2 Max and activities.
  • OAuth with GitHub locks the /mcp endpoint. When Claude connects, you sign in with GitHub, and only the GitHub username you configured gets through.
  • Privacy scrubbing. Garmin's activity data includes your name, profile photo and GPS start point, which is often your front door. The server removes those before anything reaches Claude.

What it costs: nothing

Piece Cost
Garmin Connect Personal API Free
Cloudflare Workers, Free plan (100,000 requests a day) Free
Workers KV, Free plan (100,000 reads, 1,000 writes a day) Free. The server writes about once a day
GitHub OAuth app Free
Claude Works on the Free plan, which allows one custom connector
Custom domain Optional, about $10 a year. The free workers.dev address is fine
Total $0

One person asking a few questions a day uses a tiny fraction of those limits.

Build your own

Everything is in a public template. You don't need to write any code, and every step happens in a browser.

Get the template on GitHub →

1. Create a Garmin personal API key

Open the Personal API Key page in Garmin Connect (sign in on the web if asked), then Create Key → accept the terms → choose an expiry → Create. Copy it somewhere safe: Garmin only shows it once. Garmin's own walkthrough is in the Personal API docs.

2. Deploy the Worker

Click Deploy to Cloudflare in the template's README. It forks the repo into your GitHub account, creates the KV storage and deploys. Note your Worker's address, something like https://garmin-mcp.<you>.workers.dev.

3. Tell it who you are

In your fork, edit wrangler.jsonc. Set ALLOWED_GITHUB_LOGIN to your GitHub username and PUBLIC_URL to the Worker address, then commit. Cloudflare redeploys automatically.

4. Make a GitHub OAuth app

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. Use your Worker address as the homepage and <worker address>/callback as the callback URL. Leave wildcard matching and device flow off. Copy the Client ID and generate a Client secret.

5. Add three secrets

Cloudflare → your Worker → Settings → Variables and Secrets. Add these, each as type Secret:

Name Value
GARMIN_API_KEY your key from step 1
GITHUB_CLIENT_ID from step 4
GITHUB_CLIENT_SECRET from step 4

6. Connect Claude

Go to claude.ai → Customize → Connectors → Add custom connector, and paste <worker address>/mcp. Click Connect, approve, and sign in with GitHub. Start a new chat and try:

Summarise my last 7 days from Garmin: sleep, steps, workouts and recovery.
Enter fullscreen mode Exit fullscreen mode

Check the lock. A request without a token must be refused. This should print 401:

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://<worker>/mcp
Enter fullscreen mode Exit fullscreen mode

Want to hack on it?

The repo includes a .dev.vars.example, so local setup takes three commands:

cp .dev.vars.example .dev.vars   # then fill it in
npm run check-garmin             # tests your Garmin key
npm run dev                      # http://localhost:8787
Enter fullscreen mode Exit fullscreen mode

Fill .dev.vars with your Garmin key and a second GitHub OAuth app whose callback is http://localhost:8787/callback.

Point the MCP Inspector at http://localhost:8787/mcp to try the tools. Claude connects from the cloud and can't reach localhost, so deploy before connecting it.

Things I learned along the way

  • Lock first, then add data. The endpoint requires sign-in from the very first deploy, and the Garmin key goes in last. If a step goes wrong, there's no window where your health data is public.
  • Use an exact callback URL. Leave GitHub's wildcard redirect matching off. It's a common way to leak OAuth codes.
  • Ask questions, not for raw data. "Compare this week's sleep with last week's" works far better than "give me my sleep data". Claude picks the right tools and date ranges.
  • Start a strength workout on the watch. Otherwise gym sessions are invisible to your data, and so to your check-ins.

Credits

The endpoint list and auth flow come from Garmin's official connect-personal-api-python client and the Personal API docs. The server is built on Cloudflare's workers-oauth-provider and the MCP TypeScript SDK.

This isn't medical advice. Check a new training plan with your doctor, especially if you have a health condition.

Originally published at blog.yershalom.com.

Top comments (0)