# 🏃 Garmin AI Coach — MCP Server

A fully cloud-hosted MCP server that gives Claude direct access to your Garmin Connect data.
Runs free on Vercel + Upstash. Works on any device — laptop, phone, tablet.

## What it does

- **Morning check-in**: Claude reads your HRV, sleep, body battery, and stress, then tells you whether to train hard, go easy, or rest — with actual reasoning.
- **Post-run debrief**: Analyzes running dynamics (cadence, ground contact time, vertical oscillation), pacing, and HR data.
- **Weekly review**: Training load trends, volume, intensity distribution, recovery quality.
- **Goal tracking**: Progress toward sub-38 10km via VO2max trend, race predictions, PRs.
- **Coach profile**: Claude interviews you over a few sessions to build deep knowledge of your training history, goals, injury history, and preferences — then uses it every session.

## Stack (100% free)

| Service | What it does | Cost |
|---|---|---|
| Vercel hobby | Hosts the MCP server | Free |
| Upstash Redis | Stores Garmin tokens + cached data + coach profile | Free (10k req/day) |
| garminconnect 0.3.4 | Talks to Garmin Connect API | Free |
| claude.ai Pro | Your AI coach brain | Your existing plan |

---

## Deploy in 5 steps

### Step 1 — Fork and deploy to Vercel

1. Fork this repo to your GitHub account
2. Go to [vercel.com](https://vercel.com) → New Project → Import your fork
3. Vercel auto-detects Python. Click **Deploy**.
4. Note your deployment URL: `https://your-project.vercel.app`

### Step 2 — Set up Upstash Redis

1. Go to [upstash.com](https://upstash.com) → Create account → Create Redis database
2. In Vercel: your project → **Storage** tab → **Connect Store** → select Upstash Redis
3. This automatically injects `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` into your env vars

### Step 3 — Set environment variables in Vercel

In your Vercel project → **Settings** → **Environment Variables**, add:

```
ADMIN_SECRET = some-random-secret-only-you-know
```

Generate a strong random value, e.g. from [1password.com/password-generator](https://1password.com/password-generator/).
You'll need this once for setup, then you can forget it.

Click **Redeploy** after adding env vars.

### Step 4 — Register yourself and connect Garmin

Install dependencies locally (one-time):
```bash
pip install httpx
```

Run the setup script:
```bash
MCP_URL=https://your-project.vercel.app/api/mcp python scripts/setup.py
```

Follow the prompts:
1. Enter your `ADMIN_SECRET`
2. Enter a label for yourself (e.g. "Alex")
3. The script generates your API key — **save it somewhere safe**
4. Enter your Garmin Connect email and password (used once, then discarded)

Repeat for your friend — they run the same script with the same `MCP_URL`.

### Step 5 — Connect to Claude

1. Open [claude.ai](https://claude.ai) on any device
2. Go to **Settings → Connectors → Add custom connector**
3. Name: `Garmin Coach`
4. URL: `https://your-project.vercel.app/api/mcp`
5. Click **Add**

Done. The connector is now available across claude.ai, Claude Desktop, and the mobile app.

---

## First session

Start a conversation with Claude, enable the Garmin Coach connector, then paste your system prompt:

> Open `COACH_SYSTEM_PROMPT.md` and paste its full contents into Claude → **Settings → Custom Instructions**.

Then say:
```
My API key is: [your-api-key]
Let's start my onboarding — interview me as my new coach.
```

Claude will ask you questions one at a time, building up your athlete profile across the session.

---

## Daily use examples

**Morning:**
```
Morning check-in. API key: [key]
```

**After a run:**
```
Just got back from a tempo run. API key: [key] — debrief me.
```

**Weekly:**
```
Weekly review please. API key: [key]
```

**Goal check:**
```
How am I tracking for sub-38? API key: [key]
```

---

## For your friend

They need:
1. **Claude account** (free plan works)
2. Run `python scripts/setup.py` with the same `MCP_URL`
3. Ask you for the `ADMIN_SECRET` to register their own API key
4. Add the connector URL to their Claude account
5. Paste the system prompt into their custom instructions

Each person has completely separate data in Redis. No cross-contamination.

---

## Security notes

- Your Garmin email/password is sent once during setup, used to get OAuth tokens, then never stored
- OAuth tokens are stored in Redis with a 1-year TTL and auto-refresh
- API keys are stored as SHA-256 hashes in Redis — never the raw key
- All traffic is HTTPS (Vercel enforces TLS)
- The `ADMIN_SECRET` is only needed for initial setup — share it with your friend briefly, then change it in Vercel env vars if you want to lock it down

---

## Troubleshooting

**"No Garmin tokens found"**: Re-run `scripts/setup.py` — your Redis tokens may have expired.

**"Invalid API key"**: Double-check you're using the exact key from setup. Generate a new one if needed.

**Timeout errors**: The Vercel free tier has a 10s limit. Historical data tools (`get_running_history` with many weeks) may time out — try smaller date ranges.

**Garmin login fails**: Garmin sometimes blocks programmatic login. Try again after a few minutes, or check if your Garmin account has 2FA enabled (disable it temporarily for setup).