Garmin Health

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

An MCP (Model Context Protocol) 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

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

{
  "mcpServers": {
    "garmin-health": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-health-mcp-server/index.js"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "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:

   # Windows PowerShell
   setx GARMIN_EMAIL "[email protected]"
   setx GARMIN_PASSWORD "your-password"
   

   # Linux/macOS
   export GARMIN_EMAIL="[email protected]"
   export GARMIN_PASSWORD="your-password"
   

2. Authenticate with Garmin:

   npm run auth
   

3. Start Claude Code from any directory:

   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.

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 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 - Automated health monitoring and proactive check-ins for Clawdbot
• python-garminconnect - The Python library we use to access Garmin's API

Development

# 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 - MCP SDK
• python-garminconnect - Garmin API wrapper
• fitparse - FIT file parsing
• gpxpy - GPX file handling

---

💖 Support This Project

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

---

Questions or issues? Open an issue on GitHub!