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