# Garmin MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes your **Garmin Connect**
health and running data as tools — so an LLM like **DeepSeek** can analyze your
watch data daily and coach you like a running/health coach that adapts to your
actual numbers.

```
Garmin watch ──sync──▶ Garmin Connect ──▶ garmin-mcp (this server)
                                                │  MCP tools (stdio / HTTP)
                                                ▼
                       DeepSeek (via scripts/deepseek_chat.py) or any MCP client
                       (Claude Desktop, Cherry Studio, Cursor, Claude Code, ...)
```

## Features

- **Daily health digest** — one call returns sleep (duration/score/stages),
  resting HR, HRV (last night + weekly), body battery, stress, SpO2,
  respiration, steps, calories, intensity minutes, morning training readiness
  and any workouts for a day.
- **Run coaching data** — `get_run_analysis` aggregates volume, weighted pace,
  HR, cadence, elevation, training load and weekly trends across a date range;
  `get_activity_detail` drills into per-lap splits.
- **18 tools** covering daily metrics, series data, activities, training
  status/readiness, VO2max, race predictions, lactate threshold, HR zones,
  body composition, personal records and profile.
- **Token-based auth** — log in once (MFA-capable) and sessions are saved to
  disk; the server resumes automatically, no password prompts.
- **Mock mode** — `GARMIN_MOCK=true` serves deterministic synthetic data so you
  can test the whole pipeline before connecting a real account.
- **Built-in DeepSeek bridge** — `scripts/deepseek_chat.py` gives DeepSeek the
  tools directly (function calling), interactive or one-shot for cron.

## Requirements

- Python 3.10+ (developed on 3.13)
- A Garmin Connect account (free). Two-factor enabled accounts are supported.

## Setup

```bash
cd /Users/jai/Documents/garmin_mcp_app

# 1. Create the virtualenv and install dependencies
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Configure credentials
cp .env.example .env        # then edit .env: GARMIN_EMAIL, GARMIN_PASSWORD
```

## Log in once (interactive, handles MFA)

```bash
.venv/bin/python -m garmin_mcp.login_cli --verify
```

This authenticates with Garmin Connect, prompts for the one-time MFA code if
your account uses two-factor auth, saves the OAuth tokens to
`~/.garminconnect` (owner-only permissions), and pulls a few real data points
to confirm everything works. From then on the server needs no password.

> **Troubleshooting login:** Garmin sometimes throws a bot/captcha challenge.
> Fix: log into [connect.garmin.com](https://connect.garmin.com) once in your
> browser, then retry the login script. If you get rate-limited (429), wait a
> few minutes before retrying.

## Test without a real account (mock mode)

```bash
GARMIN_MOCK=true .venv/bin/python scripts/smoke_test.py
```

Boots the server over stdio and exercises every tool as a real MCP client —
19 checks, all expected to pass with synthetic data.

## Connect to an MCP client

Point your client at the launcher script `./garmin-mcp-server` (it resolves the
venv and `PYTHONPATH` automatically):

**Claude Desktop** — add to `claude_desktop_config.json` (or use the example in
`config/claude_desktop_config.example.json`):

```json
{
  "mcpServers": {
    "garmin": {
      "command": "/Users/jai/Documents/garmin_mcp_app/garmin-mcp-server",
      "type": "stdio"
    }
  }
}
```

**Cherry Studio** (DeepSeek-friendly desktop chat): Settings → MCP Servers →
Add: Name `garmin`, type `stdio`, command
`/Users/jai/Documents/garmin_mcp_app/garmin-mcp-server`, and select your
DeepSeek provider as the model. Credentials come from the project `.env`, so no
env vars are needed in the client.

**Claude Code / Cursor / Cline**: `mcp add garmin -- /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server`

**MCP Inspector** (debugging): `npx @modelcontextprotocol/inspector` and point
it at the command above — or run the server over HTTP:

```bash
./garmin-mcp-server --transport streamable-http --port 8000
```

## Connect DeepSeek directly (optional bridge)

DeepSeek's chat API speaks OpenAI-style function calling, so this repo includes
a small bridge that starts the Garmin server, hands DeepSeek its tools, and
lets it decide what to query:

```bash
.venv/bin/pip install -r requirements-deepseek.txt   # adds 'openai'
# add DEEPSEEK_API_KEY to .env (see .env.example)

# interactive coach chat (uses prompts/coach.md as the system prompt)
.venv/bin/python scripts/deepseek_chat.py

# one-shot — cron-friendly ("daily analysis" job)
.venv/bin/python scripts/deepseek_chat.py --once "How was my recovery today? What should today's run be?"
```

Write your own coaching persona in [`prompts/coach.md`](prompts/coach.md) and
pass it with `--system-prompt prompts/coach.md` (it's the default). A starter
prompt is included.

> Note: the DeepSeek **web/chat app** doesn't support MCP itself; the bridge
> above is the way to use DeepSeek with this server. Any MCP-capable client
> (Claude Desktop, Cherry Studio, Cursor, Claude Code) also works with your
> own DeepSeek API key.

## Web app (dashboard + chat)

A browser front end is included — no MCP client needed:

```bash
.venv/bin/pip install -r requirements-web.txt    # fastapi + uvicorn
./garmin-web                                     # http://127.0.0.1:8080
./garmin-web --mock                              # try it with synthetic data
./garmin-web --port 9000                         # different port
```

It shows:
- **Today cards** — sleep score/duration, HRV, body battery, resting HR, stress, steps vs goal, training readiness, workouts.
- **Charts** (last 7/14/28 days) — resting HR + HRV, sleep, body battery, steps, weekly stress, weekly run distance.
- **Recent runs table** — distance, pace, HR, cadence, elevation, training effect, load.
- **Coach chat panel** — ask questions in natural language; DeepSeek answers using your live Garmin data (add `DEEPSEEK_API_KEY` to `.env`). The dashboard itself works without a key.

The web app keeps one MCP session to the Garmin server open for its whole lifetime, so it reuses the exact same tools and auth as every other client. The charts use the Chart.js CDN, so the browser needs internet access.

## Available tools

| Tool | Returns |
|---|---|
| `get_health_snapshot(date)` | Full daily digest: sleep, HR, HRV, body battery, stress, SpO2, readiness, activities |
| `get_daily_summary(date)` | Steps/goal, distance, calories, floors, intensity minutes, HR, stress, SpO2, respiration |
| `get_steps(date)` / `get_heart_rate(date)` / `get_stress(date)` / `get_body_battery(date)` | Daily series with hourly averages |
| `get_sleep(date)` | Duration, score, qualifier, stage breakdown, sleep SpO2 |
| `get_hrv(date)` | Last-night avg/min/max, weekly average, status |
| `get_resting_heart_rate(start, end)` | Daily RHR series over a range |
| `get_health_series(start, end)` | Aligned per-date rows (RHR, body battery, sleep, HRV, steps, runs) + weekly stress — powers the dashboard charts |
| `get_activities(start, end, activity_type?)` | Activity list with pace, HR, cadence, TE, VO2max, load |
| `get_activity_detail(activity_id)` | Single activity + per-lap splits |
| `get_run_analysis(start, end)` | Coach rollup: volume, weighted pace, weekly trends, per-run rows |
| `get_training_status(date)` / `get_training_readiness(date)` | Garmin training load/status, morning readiness + subscores |
| `get_fitness_metrics()` | VO2max, race predictions, lactate threshold, HR zones |
| `get_body_composition(start, end)` | Weight/BMI/body-fat/muscle/bone/water history |
| `get_personal_records()` / `get_profile()` | PRs and account profile |

All outputs are JSON strings; `{"ok": true, ...}` on success,
`{"ok": false, "error": ...}` on failure. Dates are `YYYY-MM-DD` (local time).

## Project layout

```
src/garmin_mcp/
  server.py          MCP server (tools, transports, CLI)
  garmin_client.py   real Garmin Connect client (token resume, cache) + mock
  formatters.py      raw Garmin payloads → compact LLM-friendly JSON
  config.py          env / .env settings
  login_cli.py       one-time interactive login (MFA-capable)
  deepseek.py        shared DeepSeek ↔ MCP chat core (CLI + web app)
scripts/
  smoke_test.py      end-to-end MCP client test (mock by default)
  deepseek_chat.py   DeepSeek ↔ MCP bridge (interactive or --once)
  web_app.py         FastAPI backend for the web dashboard + chat
web/                 frontend (index.html, app.js, style.css)
garmin-mcp-server    executable launcher for MCP clients
garmin-web           executable launcher for the web app
config/              Claude Desktop config example
prompts/coach.md     your coach system prompt (edit me)
```

## Notes & caveats

- This uses Garmin's **unofficial** (web/device) endpoints via the community
  `garminconnect` library. Garmin can change these at any time; the formatters
  are written defensively so missing fields degrade gracefully.
- Token files contain long-lived refresh tokens — keep them private
  (`~/.garminconnect`, written `0600`).
- The server caches responses for `GARMIN_CACHE_TTL` seconds (default 600) to
  avoid hammering Garmin when the LLM asks overlapping questions.
- The web dashboard charts load Chart.js from a CDN — the browser needs
  internet access for the charts (cards and the table still work offline).
- Not affiliated with Garmin. For personal use.

## License

MIT