Garmin Connect MCP Server

A Model Context Protocol (MCP) server for Garmin Connect integration. Access your activities, health data, training metrics, and more through Claude and other LLMs.

Overview

This MCP server provides 22 tools to interact with your Garmin Connect account, organized into 8 categories:

• Activities (3 tools) - Query activities and view detailed metrics
• Analysis (2 tools) - Compare activities and find similar workouts
• Health & Wellness (4 tools) - Access health metrics, sleep, heart rate, and activity data
• Training (3 tools) - Analyze training periods and performance trends
• User Profile (1 tool) - Access profile, statistics, and personal records
• Challenges & Goals (2 tools) - Track goals, PRs, badges, and challenges
• Devices & Gear (2 tools) - Manage devices and equipment
• Weight Management (2 tools) - Track weight data
• Other (3 tools) - Workouts, manual data entry, women's health tracking

Additionally, the server provides:

• 3 MCP Resources - Athlete profile, training readiness, and daily health for ongoing context
• 6 MCP Prompts - Templates for common queries (training analysis, sleep quality, readiness checks, activity analysis, run comparison, health summary)

Prerequisites

• uv (the package requires Python 3.12+, which uv can manage), OR
• Docker

Installation & Setup

How Authentication Works

1. Credential Authentication - Run the setup command to save credentials
2. MFA Support - If MFA is enabled, the setup command prompts for your code
3. Token Storage - OAuth tokens saved to ~/.garminconnect/ and automatically refreshed
4. Persistence - Tokens persist across runs (UV on host, Docker requires volume mount)

Option 1: Using uvx

uvx garmin-connect-mcp auth

This will prompt for your credentials, complete Garmin authentication, and save OAuth tokens for the MCP server to reuse. It writes credentials to ~/.garminconnect.env by default and saves OAuth tokens under ~/.garminconnect/.

If you prefer manual configuration, create ~/.garminconnect.env yourself:

GARMIN_EMAIL=your-email@example.com
GARMIN_PASSWORD=your-password

Option 2: Using Docker

# Pull the image
docker pull ghcr.io/eddmann/garmin-connect-mcp:latest

Then configure credentials using one of these methods:

Interactive Setup

# Create the env file first (Docker will create it as a directory if it doesn't exist)
touch garmin-connect-mcp.env

# Run the setup script and persist generated tokens
docker run -it --rm \
  -v "/ABSOLUTE/PATH/TO/garmin-connect-mcp.env:/app/.env" \
  -v "/ABSOLUTE/PATH/TO/.garminconnect-docker:/root/.garminconnect" \
  ghcr.io/eddmann/garmin-connect-mcp:latest \
  auth

This will prompt for your credentials, complete Garmin authentication, and save credentials to garmin-connect-mcp.env. If you have MFA enabled, enter the code during this setup step.

Manual Setup

Create a garmin-connect-mcp.env file manually in your current directory:

GARMIN_EMAIL=your-email@example.com
GARMIN_PASSWORD=your-password

MFA Support for Docker

If you have MFA enabled on your Garmin account:

• Run the interactive setup command with -it so you can enter your MFA code
• The MCP server should then use saved tokens and should not prompt during runtime
• Important: Without token persistence, you'll need to authenticate again on every container restart
• Recommended: Mount the token directory as a volume during setup and server runs to persist tokens

To persist tokens across Docker runs, create a directory for tokens and mount it:

# Create token directory on host
mkdir -p ~/.garminconnect-docker

# Then use this directory in your Docker configuration (see Claude Desktop Configuration below)

Claude Desktop Configuration

Add to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using uvx

After running uvx garmin-connect-mcp auth, configure Claude Desktop to start the published package:

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-connect-mcp"]
    }
  }
}

Using Local Source

For development, run from a local checkout:

cd garmin-connect-mcp
uv sync
uv run garmin-connect-mcp auth

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABSOLUTE/PATH/TO/garmin-connect-mcp",
        "garmin-connect-mcp"
      ]
    }
  }
}

Using Docker

Without Token Persistence (MFA required on every restart)

{
  "mcpServers": {
    "garmin": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/garmin-connect-mcp.env:/app/.env",
        "ghcr.io/eddmann/garmin-connect-mcp:latest"
      ]
    }
  }
}

With Token Persistence (Recommended for MFA users)

{
  "mcpServers": {
    "garmin": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/garmin-connect-mcp.env:/app/.env",
        "-v",
        "/ABSOLUTE/PATH/TO/.garminconnect-docker:/root/.garminconnect",
        "ghcr.io/eddmann/garmin-connect-mcp:latest"
      ]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/.garminconnect-docker with the absolute path to your token directory. On Windows, use something like C:\\Users\\YOUR_USERNAME\\.garminconnect-docker.

Usage

Ask Claude to interact with your Garmin data using natural language. The server provides tools, resources, and prompt templates to help you get started.

Quick Start with MCP Prompts

Use built-in prompt templates for common queries (available via prompt suggestions in Claude):

• analyze_recent_training - Analyze my training over the past 30 days
• sleep_quality_report - Analyze sleep quality with recommendations
• training_readiness_check - Check if I'm ready to train hard today
• activity_deep_dive - Deep dive into a specific activity
• compare_recent_runs - Compare recent runs to track progress
• health_summary - Show comprehensive health overview

Activities

"Show me my runs from the last 30 days"
"Get details for my half marathon yesterday including splits and heart rate zones"
"Show me the comments on my latest cycling activity"

Training Analysis

"Analyze my training over the past 30 days"
"Compare my last three 10K runs"
"Find runs similar to my tempo workout from last week"

Health & Wellness

"How did I sleep last night?"
"What's my Body Battery level today?"
"Show me my stress levels and recovery status"
"Am I ready to train hard today?"

Note: The athlete profile resource (garmin://athlete/profile) and daily health resource (garmin://health/today) automatically provide ongoing context.

Performance Metrics

"What's my VO2 max trend?"
"Show me my training readiness and recent stats"

Note: List-returning tools use cursor-based pagination with default limits (10 items for activities, 7 for health data).

Available Tools

Activities (3 tools)

Tool	Description
query_activities	Query activities with pagination (by ID, date range, or specific date)
get_activity_details	Get comprehensive activity details (splits, weather, HR zones, gear)
get_activity_social	Get social details for an activity (likes, comments, kudos)

Analysis (2 tools)

Tool	Description
compare_activities	Compare 2-5 activities side-by-side
find_similar_activities	Find activities similar to a reference activity

Health & Wellness (4 tools)

Tool	Description
query_health_summary	Query daily health summaries with pagination (stats, readiness, Body Battery)
query_sleep_data	Query sleep data with stages, scores, and HRV
query_heart_rate_data	Query heart rate data with resting HR
query_activity_metrics	Query activity metrics (steps, stress, respiration, SpO2, etc.)

Training (3 tools)

Tool	Description
analyze_training_period	Analyze training over a time period with insights
get_performance_metrics	Get performance metrics (VO2 max, hill score, endurance, HRV, etc.)
get_training_effect	Get training effect and progress summary

User Profile (1 tool)

Tool	Description
get_user_profile	Get comprehensive athlete profile with stats and PRs

Challenges & Goals (2 tools)

Tool	Description
query_goals_and_records	Query goals, personal records, and race predictions
query_challenges	Query challenges and badges (by status and type)

Devices & Gear (2 tools)

Tool	Description
query_devices	Query device information (with settings, solar data, alarms)
query_gear	Query gear and equipment (with defaults and usage stats)

Weight Management (2 tools)

Tool	Description
query_weight_data	Query weight data for date or range
manage_weight_data	Add or delete weight entries

Other (3 tools)

Tool	Description
manage_workouts	Workout management (list, get, download, upload)
log_health_data	Log body composition, blood pressure, hydration
query_womens_health	Query pregnancy and menstrual cycle data

MCP Resources

Resources provide ongoing context to the LLM without requiring explicit tool calls:

Resource	Description
garmin://athlete/profile	Athlete profile with stats, zones, and PRs
garmin://training/readiness	Current training readiness and Body Battery
garmin://health/today	Today's health snapshot (steps, sleep, stress, HR)

MCP Prompts

Prompt templates for common queries (accessible via prompt suggestion in Claude):

Prompt	Description
analyze_recent_training	Analyze training over a specified period
sleep_quality_report	Sleep quality analysis with recommendations
training_readiness_check	Check if ready to train hard today
activity_deep_dive	Deep dive into a specific activity with all metrics
compare_recent_runs	Compare recent runs to identify trends
health_summary	Comprehensive health overview

License

MIT License - see LICENSE file for details

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Garmin Ltd. or any of its affiliates. All product names, logos, and brands are property of their respective owners.