🏃 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 → 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 → 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. 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):

pip install httpx

Run the setup script:

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 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).