# fitness_mcp

A generic, multi-platform fitness MCP server. It pulls data from **Garmin
Connect**, **Strava**, **Google Fit**, and **Suunto**, stores everything locally
in a single **DuckDB** file, and exposes analytics as **MCP tools** over stdio —
usable from Claude Desktop, Cursor, Windsurf, VS Code, or any MCP client.

- **Zero running infrastructure** — sync is manual, the server runs on demand.
- **Fully extensible** — adding a platform = implement one abstract class and
  register it. The tools layer never changes.
- **Read-only by design** — MCP tools only read; `fitness_query` enforces
  SELECT-only.

## Architecture

```
server.py        MCP entry point (stdio)         providers/base.py     abstract interface + dataclasses
sync.py          CLI + shared sync engine        providers/garmin.py   Garmin Connect (garth)
db/database.py   DuckDB connection + upserts      providers/strava.py   Strava (OAuth2 + httpx)
db/schema.sql    table definitions               tools/*.py            MCP tools (activities, health, …)
```

Data flow: `providers` fetch normalized records → `db` upserts them into DuckDB
→ `tools` query DuckDB and return a uniform JSON envelope.

Every tool returns:

```json
{ "success": true, "data": [...], "error": null, "meta": { "count": 42 } }
```

## Setup

### Automated (macOS / Linux)

```bash
./setup.sh                  # venv + deps + .env scaffold, then prints next steps
```

Then edit `.env`, and optionally let the script do the rest:

```bash
./setup.sh --login          # interactive Garmin login (password never stored)
./setup.sh --sync           # initial sync of all platforms
./setup.sh --claude         # install the Claude Desktop MCP config
./setup.sh --dev            # install dev deps and run the test suite
# flags combine: ./setup.sh --dev --login --sync --claude
```

A `Makefile` wraps the common actions — `make help`, `make setup`, `make login`,
`make sync`, `make serve`, `make test`, `make claude-install`.

### Automated (Windows / PowerShell)

```powershell
.\setup.ps1                  # venv + deps + .env scaffold (locked to your user), then next steps
.\setup.ps1 -Dev -Login -Sync -Claude   # switches combine, same meaning as above
```

If PowerShell blocks the script, run it once as:

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```

Then use the venv directly for the recurring commands:

```powershell
.\.venv\Scripts\python.exe login.py
.\.venv\Scripts\python.exe sync.py --platform garmin --full-history
.\.venv\Scripts\python.exe scripts\claude_config.py --write   # Claude Desktop config
```

On Windows the setup script restricts `.env` to your user account via `icacls`
(the POSIX `chmod` warning is a no-op there); the garth token cache lives under
`%USERPROFILE%\.garth`, which is already user-scoped by default.

The Claude Desktop entry can be generated or installed on its own:

```bash
python scripts/claude_config.py            # print the JSON snippet
python scripts/claude_config.py --write     # merge it into your Claude config (with backup)
```

### Manual

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # then fill in credentials
```

### Credentials (`.env`)

```bash
DUCKDB_PATH=./fitness.duckdb

# Garmin Connect (via garth)
GARMIN_EMAIL=your@email.com
GARMIN_PASSWORD=yourpassword
GARTH_HOME=~/.garth          # cached session token lives here

# Strava
STRAVA_CLIENT_ID=...
STRAVA_CLIENT_SECRET=...
STRAVA_REFRESH_TOKEN=...
```

`.env` and the DuckDB file are gitignored.

#### Strava: getting a refresh token (one time)

1. Create an API application at <https://www.strava.com/settings/api>. Note the
   **Client ID** and **Client Secret**.
2. Authorize your own account, requesting the `activity:read_all` scope. Visit
   (replace `CLIENT_ID`):

   ```
   https://www.strava.com/oauth/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=http://localhost&approval_prompt=force&scope=activity:read_all
   ```

   After approving, the browser redirects to `http://localhost/?...&code=AUTH_CODE&...`.
   Copy `AUTH_CODE` from the URL.
3. Exchange the code for tokens:

   ```bash
   curl -X POST https://www.strava.com/oauth/token \
     -d client_id=CLIENT_ID -d client_secret=CLIENT_SECRET \
     -d code=AUTH_CODE -d grant_type=authorization_code
   ```

   Put the `refresh_token` from the response into `STRAVA_REFRESH_TOKEN`. The
   server refreshes the short-lived access token automatically on every sync.

> Garmin uses `garth`. **Preferred login** — run it once interactively so your
> password is never written to disk:
>
> ```bash
> python login.py        # prompts for email/password (+ MFA); caches a token
> ```
>
> After that you can leave `GARMIN_PASSWORD` out of `.env`; syncs reuse the
> cached session token. (Setting the password in `.env` still works as a
> fallback for non-interactive/headless use.)

## Security of credentials & sessions

- **Nothing secret is committed** — `.env`, the DuckDB file, and the garth token
  cache (`.garth/`, `*.token`) are all gitignored.
- **Password stays off disk** — `python login.py` reads it via `getpass` and
  only persists the resulting session token. Keep `GARMIN_PASSWORD` blank.
- **Owner-only token cache** — after every Garmin login the `GARTH_HOME`
  directory and its token files are `chmod`'d to `0700`/`0600` (POSIX).
- **Exposure warning** — `sync.py` and `server.py` warn on startup if your
  `.env` is group/world-readable, with the exact `chmod 600` fix.
- **Treat session tokens like a password** — a cached garth token grants access
  to your Garmin account. If a machine is compromised, delete `GARTH_HOME` and
  re-run `login.py`. OAuth refresh tokens (Strava/Google/Suunto) are likewise
  sensitive; revoke them in each platform's app settings if leaked.

## Syncing data

```bash
python sync.py --platform all                          # last 30 days, all platforms
python sync.py --platform garmin                       # garmin | strava | google_fit | suunto
python sync.py --platform garmin --from 2025-01-01 --to 2025-06-30
python sync.py --platform garmin --full-history        # everything from 2010 (first run)
```

Supported platforms: `garmin`, `strava`, `google_fit`, `suunto`. Garmin is the
richest source (activities, sleep, HRV, body battery, stress); Strava and Suunto
provide activities; Google Fit provides activities, sleep, and weight.

After all platforms sync, duplicate workouts (same day + sport, duration and
distance within 5%) are de-duplicated: the Garmin record is kept (richer
metrics) and the Strava id is merged into its `raw_json`.

### Recurring (automated) sync

After a one-time `python login.py`, the Garmin token auto-refreshes, so
scheduled syncs run unattended for months (re-run `login.py` only when the
long-lived token finally expires). The runner logs each run to `logs/sync.log`
and exits non-zero if any platform errored:

```bash
python scripts/scheduled_sync.py --platform all
```

**Windows (Task Scheduler):**

```powershell
.\scripts\register_sync_task.ps1                  # daily 07:00, all platforms
.\scripts\register_sync_task.ps1 -Time 06:30 -Platform garmin
.\scripts\register_sync_task.ps1 -Daily2x         # 07:00 and 19:00
.\scripts\register_sync_task.ps1 -Unregister      # remove it
```

The task runs as your user via S4U (no stored password, runs whether or not
you're logged in) and catches up missed runs. Trigger a test run with
`Get-ScheduledTask fitnessmcp-sync | Start-ScheduledTask`.

**macOS/Linux (cron):** point cron at the same runner —

```cron
0 7 * * *  cd /path/to/fitMCP && .venv/bin/python scripts/scheduled_sync.py --platform all
```

## Running the MCP server

```bash
python server.py        # serves over stdio
```

### Claude Desktop config

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "fitness": {
      "command": "/absolute/path/to/fitness-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/fitness-mcp/server.py"],
      "env": { "PYTHONPATH": "/absolute/path/to/fitness-mcp" }
    }
  }
}
```

## MCP tools

| Tool | Purpose |
|---|---|
| `fitness_sync(platform)` | Sync garmin/strava/all into DuckDB |
| `fitness_sync_status()` | Last sync time + record counts per platform |
| `fitness_get_database_stats()` | Row counts, date ranges, file size |
| `fitness_get_activities(date_from, date_to, platform, sport_type, limit, offset)` | Paginated activity list |
| `fitness_get_activity_detail(activity_id)` | Full detail incl. raw payload |
| `fitness_get_personal_bests(sport_type)` | Longest, fastest, max HR, most elevation |
| `fitness_get_sleep(date_from, date_to, platform)` | Sleep records |
| `fitness_get_hrv(date_from, date_to, platform)` | HRV + body battery |
| `fitness_get_body_battery(date_from, date_to)` | Body battery trend |
| `fitness_get_recovery_status(date)` | One-day recovery snapshot |
| `fitness_get_training_load(weeks, platform)` | Weekly load trend |
| `fitness_get_vo2max_trend(months)` | VO2max estimates over time |
| `fitness_get_weekly_summary(week_offset)` | Week totals + sport split |
| `fitness_get_sport_breakdown(date_from, date_to)` | Time/distance/count per sport |
| `fitness_compare_platforms(metric, date_from, date_to)` | Same metric per platform |
| `fitness_correlate(metric_a, metric_b, date_from, date_to)` | Pearson correlation + scatter |
| `fitness_get_trends(metric, date_from, date_to, granularity)` | Time series by day/week/month |
| `fitness_query(sql)` | Read-only SELECT against the database |

Metrics for `fitness_correlate` / `fitness_get_trends`: `sleep_score`,
`sleep_duration`, `hrv`, `hrv_score`, `body_battery`, `training_load`,
`distance`, `duration`, `avg_hr`, `stress`, `weight`.

## FitBrain — coaching layer

For a data-driven coaching experience, create a Claude Project named **FitBrain**
and paste [`prompts/fitbrain_system_prompt.md`](prompts/fitbrain_system_prompt.md)
into its custom instructions (edit the "Who I am"/"Goals" to match you). It makes
Claude always check freshness and pull live data before answering, hunt for
correlations, flag overtraining signals, and stay direct. See
[`prompts/README.md`](prompts/README.md) for setup and example questions.

## Tests

```bash
pip install -r requirements-dev.txt
PYTHONPATH=. pytest
```

The suite covers the DuckDB layer (upsert idempotency, dedup, sync log),
provider payload parsing for all four platforms, the read-only SQL guard, and
every MCP tool end-to-end against a seeded temp database — no network or
credentials required. CI runs it on every push and pull request
(`.github/workflows/tests.yml`).

## Adding a new platform

1. Create `providers/newplatform.py` extending `FitnessProvider`.
2. Add credentials to `.env`.
3. Register it in `sync.py`: `PROVIDERS["newplatform"] = NewPlatformProvider`.

Done — every tool includes it automatically when `platform="all"`.

## Project status

Implemented: foundation, all four providers (Garmin, Strava, Google Fit,
Suunto), cross-platform dedup, the full tools layer (activities, health,
training, analysis, sync), credential/session hardening, automated setup
(macOS/Linux/Windows), scheduled recurring sync, the FitBrain coaching prompt,
and a pytest suite with CI. Google Fit has no HRV and Suunto exposes only
workouts via its public API; both still satisfy the common `FitnessProvider`
interface, so the tools layer treats them uniformly.

What's left is live validation against real accounts (needs your credentials).