# Claude Code Setup Guide
This guide shows you how to use the Garmin Health MCP Server with Claude Code CLI.
## Prerequisites
1. **Claude Code CLI installed**
- Install from: https://claude.ai/download
- Verify: `claude --version`
2. **Node.js 18 or higher**
- Download from: https://nodejs.org/
- Verify: `node --version`
3. **Python 3.8 or higher**
- Download from: https://python.org/
- Verify: `python --version` or `python3 --version`
4. **Garmin Connect account**
- Sign up at: https://connect.garmin.com/
## Quick Setup (5 minutes)
### Step 1: Clone and Install Dependencies
```bash
# Clone the repository
git clone https://github.com/yourusername/garmin-health-mcp-server.git
cd garmin-health-mcp-server
# Install Node.js dependencies
npm install
# Install Python dependencies
pip3 install -r requirements.txt
```
### Step 2: Set Environment Variables
The MCP server requires your Garmin Connect credentials via environment variables.
#### Option A: Windows System Environment Variables (Recommended)
```powershell
# Open PowerShell as Administrator and run:
setx GARMIN_EMAIL "your-email@example.com"
setx GARMIN_PASSWORD "your-password"
# Restart your terminal for changes to take effect
```
#### Option B: Windows User Environment Variables (GUI)
1. Press `Win + R`, type `sysdm.cpl`, press Enter
2. Go to "Advanced" tab → "Environment Variables"
3. Under "User variables", click "New"
4. Add `GARMIN_EMAIL` with your email
5. Add `GARMIN_PASSWORD` with your password
6. Click OK and restart your terminal
#### Option C: Linux/macOS Shell Profile
Add to `~/.bashrc` or `~/.zshrc`:
```bash
export GARMIN_EMAIL="your-email@example.com"
export GARMIN_PASSWORD="your-password"
```
Then reload: `source ~/.bashrc` (or `source ~/.zshrc`)
### Step 3: Authenticate with Garmin
```bash
# Run authentication (uses environment variables)
npm run auth
# You should see:
# 🔐 Logging in as your-email@example.com...
# ✅ Tokens saved to D:\garmin-health-mcp-server\.garmin-tokens
# ✅ Login successful!
```
This creates authentication tokens in `.garmin-tokens/` that will be used by the MCP server.
### Step 4: Configure Claude Code
The repository includes a `.mcp.json` file that Claude Code will automatically detect. No additional configuration needed!
**What's in `.mcp.json`:**
```json
{
"mcpServers": {
"garmin-health": {
"type": "stdio",
"command": "node",
"args": ["D:\\garmin-health-mcp-server\\index.js"],
"env": {
"GARMIN_EMAIL": "${GARMIN_EMAIL}",
"GARMIN_PASSWORD": "${GARMIN_PASSWORD}"
}
}
}
}
```
**Important**: Update the path in `args` if you installed the server in a different location.
### Step 5: Test in Claude Code
```bash
# Start Claude Code from any directory
claude
# Check MCP server status
/mcp
# You should see:
# garmin-health - Connected
```
Now try asking Claude about your Garmin data:
- "How did I sleep last night?"
- "What's my HRV trend this week?"
- "Show me my activities from yesterday"
- "What's my body battery level?"
## Available Tools
Once configured, you'll have access to 9 Garmin health tools:
| Tool | Description |
|------|-------------|
| `get_sleep_data` | Sleep stages, duration, quality scores |
| `get_hrv_data` | Heart rate variability and sleep HRV |
| `get_body_battery` | Body battery charge/drain over time |
| `get_activity_list` | List of activities (runs, rides, etc.) |
| `get_activity_details` | Detailed metrics for specific activity |
| `get_activity_file` | Download FIT/GPX files |
| `get_stress_data` | Stress levels throughout the day |
| `get_respiration_data` | Respiration rate data |
| `generate_dashboard` | Create HTML charts for health metrics |
## Troubleshooting
### Error: "GARMIN_EMAIL and GARMIN_PASSWORD environment variables not set"
**Cause**: Environment variables are not available to Claude Code.
**Fix**:
1. Verify variables are set: `echo %GARMIN_EMAIL%` (Windows) or `echo $GARMIN_EMAIL` (Linux/macOS)
2. Restart your terminal after setting environment variables
3. On Windows, use `setx` to persist variables across sessions
### Error: "python3: command not found"
**Cause**: Python is not in your system PATH.
**Fix**:
- **Windows**: Reinstall Python with "Add Python to PATH" checked
- **Linux/macOS**: Install Python 3 via package manager (apt, brew, etc.)
- **Alternative**: Update `.mcp.json` to use full Python path
### Error: "Authentication failed"
**Cause**: Invalid credentials or expired tokens.
**Fix**:
1. Verify your credentials are correct
2. Run `npm run auth` to re-authenticate
3. Check Garmin Connect is accessible: https://connect.garmin.com/
### Error: "garmin-health server not found"
**Cause**: Claude Code cannot find the MCP server configuration.
**Fix**:
1. Verify `.mcp.json` exists in the project directory
2. Check the path in `args` matches your actual installation location
3. Run `claude` from within the garmin-health-mcp-server directory
### MCP Server Shows as "Disconnected"
**Cause**: Server startup error or dependency issue.
**Fix**:
1. Test the server manually: `node index.js`
2. Check all dependencies installed: `npm install` and `pip3 install -r requirements.txt`
3. Review error logs in Claude Code output
### Token Refresh Issues
**Cause**: Garmin tokens expire after a period of inactivity.
**Fix**:
- Run `npm run auth` to refresh tokens
- Tokens auto-refresh on use, but may need manual refresh after long inactivity
## Advanced Configuration
### Custom Token Storage Location
By default, tokens are stored in `.garmin-tokens/` within the MCP server directory. To change this:
1. Edit `scripts/garmin_auth.py` line 21
2. Update `TOKEN_DIR` to your preferred location
3. Run `npm run auth` to create tokens in the new location
### Multiple Garmin Accounts
To use multiple Garmin accounts:
1. Create separate copies of the MCP server directory
2. Configure each with different credentials
3. Add multiple servers to `.mcp.json` with unique names
### Running Alongside Claude Desktop
You can use both Claude Code and Claude Desktop with the same MCP server:
- **Claude Code**: Uses `.mcp.json` in the project directory
- **Claude Desktop**: Uses `claude_desktop_config.json` in `%APPDATA%\Claude\`
- **Both share the same tokens** stored in `.garmin-tokens/`
No conflicts - they work independently but access the same Garmin account.
## Environment Variable Security
**Important**: Environment variables are visible to all processes running under your user account.
**Best practices**:
- Never commit `.env` files with credentials to git
- Use system/user environment variables (not shell history)
- Consider using a password manager to store credentials
- Rotate your Garmin password periodically
**Alternative**: For development, you can hardcode credentials in `.mcp.json` (NOT recommended for production or shared repositories):
```json
{
"mcpServers": {
"garmin-health": {
"type": "stdio",
"command": "node",
"args": ["D:\\garmin-health-mcp-server\\index.js"],
"env": {
"GARMIN_EMAIL": "your-email@example.com",
"GARMIN_PASSWORD": "your-actual-password"
}
}
}
}
```
**⚠️ Warning**: This approach exposes credentials in plain text. Only use for local development.
## Example Usage
### Daily Health Check
```
User: "Give me my health summary for today"
Claude: I'll fetch your Garmin health data for today...
- Sleep: 7h 23m (92% quality)
- Body Battery: Started at 85, currently 42
- Stress: Average 31 (low)
- HRV: 58ms (good recovery)
- Activities: 1 run, 5.2km in 28 minutes
```
### Weekly Analysis
```
User: "How's my HRV trending this week?"
Claude: Let me analyze your HRV data for the past 7 days...
[Fetches data and provides analysis of trends]
```
### Activity Tracking
```
User: "What activities did I do in January 2026?"
Claude: I'll get your activity list for January...
[Lists all activities with dates, types, distances, durations]
```
### Visual Dashboards
```
User: "Create a sleep dashboard for the past month"
Claude: I'll generate a comprehensive sleep dashboard...
[Creates HTML file with interactive charts]
```
## Next Steps
- Try asking Claude about different health metrics
- Explore chart generation: "Create a body battery dashboard"
- Set up recurring queries: "Remind me to check my weekly HRV"
- Combine with other MCP servers for comprehensive health tracking
## Support
- **Issues**: https://github.com/yourusername/garmin-health-mcp-server/issues
- **Discussions**: https://github.com/yourusername/garmin-health-mcp-server/discussions
- **MCP Documentation**: https://modelcontextprotocol.io/
## Related Guides
- [Installation Guide](INSTALL.md) - Detailed installation for all platforms
- [README](README.md) - Project overview and features
- [Claude Desktop Setup](README.md#claude-desktop-setup) - Configure for Claude Desktop app
