Garmin Health MCP Server

Garmin Health MCP Server

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

   # Windows PowerShell
   setx GARMIN_EMAIL "your-email@example.com"
   setx GARMIN_PASSWORD "your-password"
   

   # Linux/macOS
   export GARMIN_EMAIL="your-email@example.com"
   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:

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