# Garmin MCP Server

Connect your Garmin watch data to Claude Desktop. This is a lightweight
[Model Context Protocol](https://modelcontextprotocol.io) server that lets
Claude answer questions like *"How did I sleep last night?"* or *"Summarize
my workouts this week"* using your real Garmin Connect data.

![Claude Desktop answering a weekly health summary question with Garmin data](screenshot.png)

## Tools

| Tool | What it returns |
|------|-----------------|
| `get_daily_steps` | Step count and step goal for a date |
| `get_daily_summary` | Steps, calories, distance, floors, intensity minutes, resting HR, stress, body battery |
| `get_sleep` | Sleep duration, deep/light/REM/awake breakdown, sleep score |
| `get_heart_rate` | Resting, min, max, and 7-day average resting heart rate |
| `get_recent_activities` | Recent workouts with distance, duration, pace, calories, heart rate |
| `get_stress` | Average and max stress level for a date |

## Setup

Requires Python 3.10+ and [Claude Desktop](https://claude.ai/download).

```bash
git clone https://github.com/cadencheng888/garmin-mcp.git
cd garmin-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 1. Log in to Garmin (one time)

```bash
python garmin_login.py
```

Enter your Garmin Connect email and password (and an MFA code if your
account uses one). OAuth tokens are saved to `~/.garminconnect` and last
about a year — your password is never stored anywhere. If you see
`429 — IP rate limited by Garmin` warnings, ignore them; the library
falls back to another login method automatically.

### 2. Add the server to Claude Desktop

Edit your Claude Desktop config:

- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

### 3. Try it

Fully quit Claude Desktop (Cmd+Q) and reopen it. Click the tools icon in
the chat input to confirm the server is listed, then ask:

> How many steps did I take yesterday?

## Adding more tools

Add another `@mcp.tool()` function in `server.py` that calls any
[`garminconnect`](https://github.com/cyberjunky/python-garminconnect) method
(body battery, VO2 max, training status, hydration, weight, and more), then
restart Claude Desktop.

## Disclaimer

This project uses the unofficial `garminconnect` library, which talks to
Garmin's private API. It is not affiliated with or endorsed by Garmin, and
the API can change without notice. Use at your own risk.