# Garmin Health MCP Server

> **Access your Garmin Connect health data directly in Claude Desktop and Claude Code CLI**

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides Claude with access to your Garmin wearable health data including sleep, recovery, HRV, workouts, and more.

## Features

- 🛌 **Sleep Analysis**: Hours, stages (light/deep/REM), quality scores
- 🔋 **Body Battery**: Garmin's proprietary recovery metric (0-100)
- ❤️ **HRV Tracking**: Heart rate variability trends for recovery monitoring
- 🏃 **Activity Data**: Workouts by type, calories, duration, pace
- 📊 **Health Metrics**: Resting heart rate, stress levels, VO2 max
- 📈 **Interactive Charts**: Generate beautiful HTML dashboards
- 🔐 **Secure**: Credentials stored locally, connects only to Garmin's API

## Quick Start

### Prerequisites

- **Claude Desktop** or **Claude Code CLI** installed
- **Node.js** 18+ and npm
- **Python** 3.8+
- Active Garmin Connect account with a connected device

### Installation

```bash
# 1. Clone this repository
git clone https://github.com/eversonl/garmin-health-mcp-server.git
cd garmin-health-mcp-server

# 2. Install Node.js dependencies
npm install

# 3. Install Python dependencies
pip3 install garminconnect fitparse gpxpy
# Or on managed systems:
pip3 install --user garminconnect fitparse gpxpy

# 4. Create .env file with your Garmin credentials
cp .env.example .env
# Edit .env and add your GARMIN_EMAIL and GARMIN_PASSWORD

# 5. Authenticate with Garmin Connect
npm run auth
```

### Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

Add this MCP server configuration:

```json
{
  "mcpServers": {
    "garmin-health": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-health-mcp-server/index.js"],
      "env": {
        "GARMIN_EMAIL": "your-email@example.com",
        "GARMIN_PASSWORD": "your-password"
      }
    }
  }
}
```

**Important**: Replace `/absolute/path/to/garmin-health-mcp-server/` with the actual full path where you cloned this repo.

### Restart Claude Desktop

Completely quit and restart Claude Desktop for the MCP server to load.

## Using with Claude Code CLI

For Claude Code CLI users, this repository includes a `.mcp.json` configuration file that enables automatic MCP server loading.

### Quick Setup for Claude Code

1. **Set environment variables** with your Garmin credentials:
   ```powershell
   # Windows PowerShell
   setx GARMIN_EMAIL "your-email@example.com"
   setx GARMIN_PASSWORD "your-password"
   ```

   ```bash
   # Linux/macOS
   export GARMIN_EMAIL="your-email@example.com"
   export GARMIN_PASSWORD="your-password"
   ```

2. **Authenticate with Garmin**:
   ```bash
   npm run auth
   ```

3. **Start Claude Code** from any directory:
   ```bash
   claude
   ```

4. **Verify the MCP server is loaded**:
   ```
   /mcp
   ```
   You should see `garmin-health` listed as connected.

5. **Start querying your health data**:
   > "How did I sleep last night?"

   > "What's my body battery level today?"

**📘 For detailed Claude Code setup instructions**, see [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md).

**Note**: The `.mcp.json` file uses environment variable expansion for security. Update the `args` path if you installed the server in a different location.

## Usage

Once configured, ask Claude questions like:

> "How did I sleep last night?"

> "What's my Body Battery looking like this week?"

> "Show me my activities from the past month"

> "Is my HRV improving?"

> "Generate a health dashboard for the last 30 days"

Claude will use the MCP tools to fetch your Garmin data and provide insights.

## Available Tools

The server exposes these tools to Claude:

| Tool | Description |
|------|-------------|
| `get_sleep_data` | Sleep hours, stages, quality scores |
| `get_body_battery` | Recovery metric (0-100) |
| `get_hrv_data` | Heart rate variability trends |
| `get_heart_rate` | Resting, max, min heart rate |
| `get_activities` | Workout/exercise data |
| `get_stress_levels` | All-day stress tracking |
| `get_summary` | Combined health overview |
| `get_user_profile` | Account and device info |
| `generate_chart` | Create interactive HTML visualizations |

## Troubleshooting

### "MCP server not found"
- Verify the path in `claude_desktop_config.json` is absolute (starts with `/` or `C:\`)
- Check that `index.js` exists at that path
- Ensure you ran `npm install` in the repo directory

### "Authentication failed"
- Run `npm run auth` to refresh tokens
- Check your credentials in the `.env` file or environment variables
- Try logging into [Garmin Connect](https://connect.garmin.com) website to verify your account

### "Tools not appearing in Claude"
- Completely quit Claude Desktop (don't just close the window)
- Check Console.app (macOS) or Event Viewer (Windows) for MCP errors
- Verify Node.js is accessible: `node --version`
- Check Python dependencies are installed: `python3 -c "import garminconnect"`

### "Missing data"
- Some metrics require specific Garmin devices (e.g., Body Battery needs HRV-capable watches)
- Historical data may have gaps if the device wasn't worn
- New accounts may have limited history

### "Too many requests" / Rate limiting
- Garmin limits API requests - wait a few minutes before retrying
- Use the `get_summary` tool instead of calling multiple individual tools

## Privacy & Security

- ✅ Credentials stored locally in `.env` and `claude_desktop_config.json`
- ✅ Session tokens cached locally and auto-refresh
- ✅ Connects only to Garmin's official API servers
- ✅ No cloud storage or third-party data sharing
- ✅ Open source - audit the code yourself

## Related Projects

- **[Clawdbot Skill](https://github.com/eversonl/ClawdBot-garmin-health-analysis)** - Automated health monitoring and proactive check-ins for Clawdbot
- **[python-garminconnect](https://github.com/cyberjunky/python-garminconnect)** - The Python library we use to access Garmin's API

## Development

```bash
# Run the server directly (for testing)
npm start

# Test authentication
npm run auth

# Run tests
npm test
```

## License

MIT © EversonL

## Credits

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
- [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) - Garmin API wrapper
- [fitparse](https://github.com/dtcooper/python-fitparse) - FIT file parsing
- [gpxpy](https://github.com/tkrajina/gpxpy) - GPX file handling

---

## 💖 Support This Project

If you find this MCP server useful, consider supporting its development:

<a href="https://buymeacoffee.com/leeev" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

---

**Questions or issues?** [Open an issue](https://github.com/eversonl/garmin-health-mcp-server/issues) on GitHub!