# mcp-garmin

MCP server exposing Garmin Connect data to Claude Desktop.

## Setup

### 1. Install dependencies

```bash
python -m venv .venv
.venv/bin/pip install "mcp[cli]" garminconnect
```

### 2. Configure Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/mcp-garmin/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-garmin/server.py"],
      "env": {
        "GARMIN_EMAIL": "your@email.com",
        "GARMIN_PASSWORD": "yourpassword"
      }
    }
  }
}
```

Replace `/absolute/path/to/mcp-garmin` with the actual path to this directory.

### 3. Restart Claude Desktop

Quit and relaunch Claude Desktop to pick up the new server config.

### 4. First-time authentication

On first use (no cached session in `~/.garth`), ask Claude:

> "Call authenticate()"

If Garmin requires MFA, a prompt will appear in the chat. Check your email or phone for the code, then:

> "Call complete_mfa with code 123456"

Once authenticated, the session is cached in `~/.garth`. Future server restarts will log in silently without MFA.

## Available Tools

| Tool | Parameters | Description |
|------|-----------|-------------|
| `authenticate()` | — | Initiate Garmin login |
| `complete_mfa(code)` | `code: str` | Provide MFA code to finish login |
| `get_activities(start_date, end_date, limit)` | all optional | List recent activities |
| `get_activity_details(activity_id)` | `activity_id: str` | Full detail for one activity |
| `get_sleep(date)` | optional | Sleep score and stages |
| `get_heart_rate(date)` | optional | Resting HR and daily timeline |
| `get_stress(date)` | optional | Stress level timeline |
| `get_body_battery(date)` | optional | Body battery charge/drain |
| `get_hrv(date)` | optional | HRV status and nightly average |
| `get_spo2(date)` | optional | Blood oxygen readings |
| `get_steps(date)` | optional | Step count and daily goal |
| `get_daily_stats(date)` | optional | Calories, floors, intensity minutes |
| `get_devices()` | — | Paired Garmin devices |
| `get_gear()` | — | Gear items with mileage stats |
| `get_user_profile()` | — | Profile, age, weight, HR zones |

All `date` parameters accept `YYYY-MM-DD` format and default to today when omitted.

## Running Tests

```bash
.venv/bin/pytest tests/ -v
```