Garmin Connect MCP Server

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 tokensfor the MCP server to reuse. It writes credentials to ~/.garminconnect.env by defaultand saves OAuth tokens under ~/.garminconnect/.

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

[email protected]
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 togarmin-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:

[email protected]
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 thepublished 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)

Analysis (2 tools)

Health & Wellness (4 tools)

Training (3 tools)

User Profile (1 tool)

Challenges & Goals (2 tools)

Devices & Gear (2 tools)

Weight Management (2 tools)

Other (3 tools)

MCP Resources

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

MCP Prompts

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

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.