garmin-mcp
README.md
# 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.

## 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.