Metadata-Version: 2.4
Name: garmin-mcp-gt
Version: 0.1.6
Summary: Garmin Connect MCP server — exposes health and activity data as tools for Claude
Project-URL: Homepage, https://github.com/JamesWoolfenden/garmin-mcp-gt
Project-URL: Issues, https://github.com/JamesWoolfenden/garmin-mcp-gt/issues
License: MIT License
        
        Copyright (c) 2026 James Woolfenden
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,cycling,fitness,garmin,health,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Requires-Python: >=3.10
Requires-Dist: garmin-fit-sdk>=21.0.0
Requires-Dist: garminconnect<0.4,>=0.3.2
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Fuel

A calorie and activity tracker for cyclists, powered by Claude and Garmin Connect.

Log food in plain English, get a calorie balance against your activity, and ask questions about your fitness data — all from a mobile-friendly web app.

<img src="docs/screenshot-app.png" alt="Fuel app — food log view" width="390" />

## Features

- **Food logging** — describe what you ate in plain English; Claude estimates the calories
- **Activity balance** — live calorie in vs. burned, updated from Garmin
- **Conversational health advisor** — ask "how were my steps today?" or "how did I sleep last night?" and get answers using your real Garmin data
- **Push nudges** — scheduled notifications with time-aware advice (morning vs. evening)
- **Multi-user** — each user has their own data, secured with Firebase Auth

## Using the app

The hosted app is at **https://pike-477416.web.app**

1. Sign in with Google or create an email/password account
2. Log food in the text box ("had porridge and a coffee")
3. Connect Garmin to enable activity data and the Ask tab (see below)
4. Tap **Ask** to chat with Claude about your health data

## Connecting Garmin

Garmin uses session tokens that must be generated on your own machine (there is no public OAuth API). Setup takes about two minutes:

### 1. Install the CLI

```bash
pip install garmin-mcp-gt
```

### 2. Authenticate with Garmin

```bash
garmin-setup
```

Enter your Garmin Connect email and password when prompted. Tokens are saved to `~/.garmin_tokens/`.

### 3. Generate an upload token in the app

In the Fuel app, scroll to the bottom of the **Log** tab and tap **Connect Garmin**. This generates a 15-minute upload token.

### 4. Upload your tokens

```bash
garmin-upload-tokens --token "paste-token-here"
```

That's it. Your Garmin data is now available in the app and the Ask tab will use it.

**Tokens expire** periodically (weeks to months). Re-run `garmin-setup` then `garmin-upload-tokens` when needed.

## Using as an MCP server (Claude Code / Claude Desktop)

`garmin-mcp-gt` is a standalone MCP server — no app account needed. After installing and authenticating, Claude can query your Garmin data directly in any conversation.

### Setup

```bash
pip install garmin-mcp-gt
garmin-setup        # authenticate with your Garmin Connect account once
```

Then add to `~/.claude/settings.json` (Claude Code) or your Claude Desktop config:

```json
{
  "mcpServers": {
    "garmin": {
      "command": "garmin-mcp"
    }
  }
}
```

### Available tools

| Tool | Description |
|------|-------------|
| `get_today_stats` | Steps, distance, calories, active minutes, resting HR, body battery |
| `get_recent_activities` | Last N cycling/running activities with distance, duration, HR, power |
| `get_activity_detail` | Detailed metrics for one activity: HR/power zones, cadence, left/right power balance, power phase angles, platform centre offset — useful for bike fit analysis |
| `get_activity_fit` | Downloads the raw FIT file and returns TSS, Intensity Factor, total work (kJ), device FTP, and a per-lap breakdown — data not available via the Garmin API |
| `get_sedentary_analysis` | How sedentary a day was — sedentary/light/moderate/active time breakdown |
| `get_sleep` | Sleep score, stages (deep/REM/light), SpO2, stress |
| `get_hrv` | Overnight HRV history — key recovery metric |
| `get_weekly_trends` | Weekly cycling summary: km, hours, average power |
| `get_cycling_ftp` | Current FTP and W/kg |
| `get_vo2max` | VO2max and lactate threshold history |
| `get_weight` | Weigh-in history: weight, body fat %, muscle mass |
| `get_weight_trend` | Weekly rolling weight averages to track fat loss without hydration noise |
| `get_weather` | Current conditions and cycling forecast via OpenMeteo (free, no API key) — includes rideable flag per day |
| `get_activity_weather` | Weather recorded by Garmin during a specific past activity |

### Example questions

- "How did I sleep last night?"
- "Am I sedentary today?"
- "Analyse my bike fit from my last 5 rides"
- "How does my HRV trend compare to my training load this week?"
- "What's my W/kg and how has my weight changed this month?"

## Architecture

- **Frontend** — React PWA, hosted on Firebase Hosting
- **Backend** — FastAPI on Cloud Run (europe-west1)
- **Database** — SQLite with Litestream replication to GCS (zero managed DB cost)
- **Garmin tokens** — encrypted at rest with Cloud KMS, per-user in SQLite
- **Auth** — Firebase Auth (Google Sign-In + email/password)
- **AI** — Claude API (food parsing, recommendations, conversational tools)

## Self-hosting

The backend is a standard Cloud Run service. To deploy your own instance:

1. Fork this repo
2. Create a GCP project and enable the required APIs
3. Run `backend/setup-wif.ps1` to configure GitHub Actions auth
4. Run `backend/setup-secrets.ps1` to store your secrets
5. Add GitHub Actions secrets (see `backend/setup-wif.ps1` output)
6. Push to main — CI deploys everything automatically

Infrastructure is managed with OpenTofu — see `terraform/`.

## Development

```bash
# Python tests
python -m pytest

# Frontend tests
cd ui && npm test

# Run backend locally
DB_PATH=./dev.db uvicorn backend.main:app --reload
```
