# Installation Guide
Choose your installation path based on your use case:
**New to MCP?** Start with 🟣 Claude Code CLI for the simplest setup!
## 🟣 For Claude Code CLI Users (Recommended)
**Best for**: Command-line interface, project-based workflows, simple environment variable configuration
### Quick Install
```bash
# 1. Clone and setup
git clone https://github.com/eversonl/garmin-health-mcp-server.git
cd garmin-health-mcp-server
npm install
# 2. Install Python dependencies
pip3 install garminconnect fitparse gpxpy
# 3. Set environment variables
# Windows (PowerShell as Administrator):
setx GARMIN_EMAIL "your-email@example.com"
setx GARMIN_PASSWORD "your-password"
# Linux/macOS (add to ~/.bashrc or ~/.zshrc):
export GARMIN_EMAIL="your-email@example.com"
export GARMIN_PASSWORD="your-password"
# 4. Restart your terminal, then authenticate
npm run auth
# 5. Test the server
npm test
```
### Configure Claude Code
The repository includes a `.mcp.json` file that Claude Code automatically detects. **No additional configuration needed!**
**Important**: Update the path in `.mcp.json` if you installed the server in a different location:
```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}"
}
}
}
}
```
### Verify
Start Claude Code and test:
```bash
# Start Claude Code
claude
# Check MCP server status
/mcp
# Ask Claude about your health data
```
Try asking:
> "How did I sleep last night?"
> "What's my body battery today?"
> "Show me my activities this week"
**📘 For detailed setup instructions**, see [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md).
---
## 🔵 For Claude Desktop Users (MCP Server)
**Best for**: Using Garmin data in Claude Desktop app, no Clawdbot needed
### Quick Install
```bash
# 1. Clone and setup
git clone https://github.com/eversonl/garmin-health-mcp-server.git
cd garmin-health-mcp-server
npm install
# 2. Install Python dependencies
pip3 install garminconnect fitparse gpxpy
# 3. Setup credentials
cp .env.example .env
# Edit .env with your Garmin email/password
# 4. Authenticate
npm run auth
# 5. Test
npm test
```
### Configure Claude Desktop
Edit your config 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:
```json
{
"mcpServers": {
"garmin-health": {
"command": "node",
"args": ["/FULL/PATH/TO/garmin-health-mcp-server/index.js"],
"env": {
"GARMIN_EMAIL": "your-email@example.com",
"GARMIN_PASSWORD": "your-password"
}
}
}
}
```
**⚠️ Use the FULL absolute path** where you cloned the repo!
Restart Claude Desktop completely (quit, don't just close window).
### Verify
Ask Claude:
> "What Garmin tools do you have?"
> "How did I sleep last night?"
---
## 🟢 For Clawdbot Users (Skill)
**Best for**: Automated health monitoring, scheduled reports, integration with other skills
### Quick Install
```bash
# Using clawdhub (recommended)
clawdhub install garmin-health-analysis
# Or manually
cd ~/.clawdbot/skills
git clone https://github.com/eversonl/ClawdBot-garmin-health-analysis.git garmin-health-analysis
cd garmin-health-analysis
bash install.sh
```
### Configure
Add to `~/.clawdbot/clawdbot.json`:
```json
{
"skills": {
"entries": {
"garmin-health-analysis": {
"enabled": true,
"env": {
"GARMIN_EMAIL": "your-email@example.com",
"GARMIN_PASSWORD": "your-password"
}
}
}
}
}
```
### Authenticate
```bash
cd ~/.clawdbot/skills/garmin-health-analysis
python3 scripts/garmin_auth.py login
```
### Verify
In Clawdbot chat:
> "Show me my Garmin health summary for the past week"
---
## 🟣🔵🟢 Using Multiple Installations?
You can use all three installations simultaneously! They share the same authentication tokens.
**Use cases:**
- **Claude Code CLI**: Quick queries from the terminal, project-based workflows
- **Claude Desktop**: Rich UI for visualizations, casual browsing
- **Clawdbot**: Automated monitoring, scheduled reports, proactive notifications
**Shared auth**: After updating to the new token storage location (`.garmin-tokens/` in the MCP server directory), all interfaces will use the same tokens. Authenticate once with `npm run auth`, and it works everywhere.
---
## Troubleshooting
### Python Dependencies
If `pip3 install` fails with "externally-managed-environment":
```bash
# Try --user flag
pip3 install --user garminconnect fitparse gpxpy
# Or --break-system-packages (if you know what you're doing)
pip3 install --break-system-packages garminconnect fitparse gpxpy
# Or use a virtual environment (recommended for advanced users)
python3 -m venv venv
source venv/bin/activate
pip install garminconnect fitparse gpxpy
```
### Authentication Fails
1. Check credentials are correct
2. Try logging into [Garmin Connect](https://connect.garmin.com) website
3. If you have 2FA enabled, you may need to create an app-specific password
4. Run auth again: `npm run auth` (MCP) or `python3 scripts/garmin_auth.py login` (Clawdbot)
### MCP Server Not Loading
1. Check path in `claude_desktop_config.json` is **absolute** (starts with `/` or `C:\`)
2. Verify `index.js` exists at that path
3. Check Claude Desktop logs:
- **macOS**: Console.app → filter for "Claude"
- **Windows**: Event Viewer
4. Try running manually: `node /path/to/index.js` to see errors
### No Data Returned
1. Check device was worn during the requested time period
2. Some metrics require specific devices (Body Battery needs HRV-capable watches)
3. New accounts may have limited historical data
4. Garmin may be rate-limiting - wait a few minutes
---
## Next Steps
- **[Read the full README](README.md)** for detailed feature documentation
- **[Check the Clawdbot SKILL.md](https://github.com/eversonl/ClawdBot-garmin-health-analysis/blob/main/SKILL.md)** for automation examples
- **[Review health_analysis.md](https://github.com/eversonl/ClawdBot-garmin-health-analysis/blob/main/references/health_analysis.md)** for metric interpretation
---
**Need help?** Open an issue on GitHub!
