Skip to main content
Glama
Garmin MCP for Claude

Garmin MCP for Claude

by yershalom
README.md
# Garmin MCP for Claude

Talk to your own Garmin data in Claude: *"How did I sleep this week?"*, *"Did my walks hit my
heart-rate target?"*, *"Show the sets I logged at the gym yesterday."*

A small, private [MCP](https://modelcontextprotocol.io) server on Cloudflare Workers that uses
Garmin's official, read-only [Connect Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api/).
It costs nothing to run for one person.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/yershalom/claude-garmin-mcp)

## How it works

```
Claude ──OAuth (GitHub sign-in, only you)──▶ Worker /mcp ──Bearer token──▶ Garmin Personal API
                                              │
                                              └─ KV: OAuth grants + cached Garmin token
```

- Your Garmin **personal API key** is a Worker secret. The Worker swaps it for a 24-hour access
  token, caches it in KV, and refreshes it an hour before it expires.
- **`/mcp` is locked.** Claude has to sign in through OAuth, which sends you to GitHub, and only the
  GitHub account in `ALLOWED_GITHUB_LOGIN` gets through.
- **Read-only.** Every tool is a `GET`. Names, profile photos and GPS coordinates are stripped from
  responses before they reach Claude.

## What it costs

| Piece | Cost |
|---|---|
| Garmin Connect Personal API | Free |
| Cloudflare Workers, Free plan (100,000 requests/day) | Free |
| Workers KV, Free plan (100,000 reads, 1,000 writes/day) | Free. This 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/year. The free `*.workers.dev` address works fine |
| **Total** | **$0** |

## Tools

| Tool | Data |
|---|---|
| `get_daily_summaries` | Steps, calories, intensity minutes, resting HR, stress, Body Battery per day |
| `get_daily_steps`, `get_daily_stress`, `get_hydration` | Per-day stats |
| `get_sleep_summaries`, `get_sleep_detail` | Sleep per night, or one night in detail |
| `get_daily_heart_rate`, `get_hrv_summaries`, `get_spo2` | Heart rate, HRV, blood oxygen |
| `get_body_battery`, `get_vo2_max`, `get_fitness_age` | Recovery and fitness |
| `get_weight` | Weight and body composition |
| `search_activities`, `get_activity`, `get_activity_workouts`, `list_activity_types` | Workouts, including strength sets and reps |
| `get_heart_rate_zones`, `get_profile_settings` | Settings |

## Set it up (about 15 minutes, all in the browser)

### 1. Garmin API key
Open the [Personal API Key page](https://connect.garmin.com/app/settings/personalApiToken) in Garmin Connect (sign in on the web if asked) →
**Create Key** → accept the terms → pick an expiry → **Create**. Copy the key: it's shown once.
Garmin's own guide: [Garmin Connect Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api/).

### 2. Deploy
Click **Deploy to Cloudflare** above. It forks this repo into your GitHub, creates the KV
namespace and deploys the Worker. Note the Worker's address, for example
`https://garmin-mcp.<your-subdomain>.workers.dev`.

Prefer doing it by hand? Fork the repo, then in Cloudflare go to **Workers & Pages → Create →
Import a repository**, pick your fork, and set the deploy command to `npx wrangler deploy`.

### 3. Set your two variables
In your fork, edit `wrangler.jsonc`:
- `ALLOWED_GITHUB_LOGIN`: your GitHub username
- `PUBLIC_URL`: the Worker address from step 2

Commit. Cloudflare redeploys on every push.

### 4. GitHub OAuth app
GitHub → **Settings → Developer settings → OAuth Apps → New OAuth App**:
- Homepage URL: your Worker address
- Authorization callback URL: your Worker address + `/callback`
- Leave wildcard matching and device flow off

Copy the **Client ID**, and generate a **Client secret**.

### 5. Secrets
Cloudflare → your Worker → **Settings → Variables and Secrets → Add**, type **Secret**:

| Name | Value |
|---|---|
| `GARMIN_API_KEY` | from step 1 |
| `GITHUB_CLIENT_ID` | from step 4 |
| `GITHUB_CLIENT_SECRET` | from step 4 |

### 6. Connect Claude
[claude.ai/customize/connectors](https://claude.ai/customize/connectors) → **Add custom
connector** → URL: your Worker address + `/mcp` → **Connect** → approve → sign in with GitHub.

Start a new chat and ask: *"Summarise my last 7 days from Garmin."*

### Check it's locked
```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://YOUR-WORKER/mcp   # must print 401
```

## Local development

```bash
npm install
cp .dev.vars.example .dev.vars      # fill in your key, a local GitHub OAuth app, your username
npm run check-garmin                # tests your Garmin key directly, no server needed
npm run dev                         # http://localhost:8787
```

For the local GitHub OAuth app, use the callback `http://localhost:8787/callback`. To try the tools,
run `npx @modelcontextprotocol/inspector` and connect to `http://localhost:8787/mcp`.
Claude itself can't reach `localhost`, so deploy before connecting Claude.

`npm run typecheck` checks the TypeScript.

## Security notes

- Secrets live only in Cloudflare (or your git-ignored `.dev.vars`). None are in the repo.
- To cut off access, remove the connector in Claude, delete the key in Garmin Connect, or both.
- The Garmin key expires on the date you picked. Make a new one and update `GARMIN_API_KEY`. The
  cached token is tied to the key, so it refreshes by itself.
- The Personal API is for your own data. Each person runs their own copy with their own key.

## Credits

Endpoint list and auth flow from Garmin's official
[connect-personal-api-python](https://github.com/garmin/connect-personal-api-python) client.
Built with [workers-oauth-provider](https://github.com/cloudflare/workers-oauth-provider) and the
[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).

MIT licensed.