Skip to main content
Glama
Garmin Connect MCP Server

Garmin Connect MCP Server

by eddmann

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.

Python 3.12+ PyPI Docker

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)

Related MCP server: Garmin MCP Server

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"
      ]
    }
  }
}
{
  "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.

Available Tools

22 tools
analyze_training_periodA
Read-only

Analyze training over a specified period with comprehensive insights.

Provides:

  • Total volume (activities, distance, time, elevation)

  • Activity type breakdown

  • Weekly trends

  • Performance insights

Example periods: "30d", "this-month", "2024-01-01:2024-01-31"

Inputs: period, activity_type, unit. Returns: result

compare_activitiesA
Read-only

Compare multiple activities side-by-side.

Analyzes 2-5 activities and provides:

  • Side-by-side metrics comparison

  • Identification of best/worst performances

  • Performance insights and patterns

Example: activity_ids="12345678,12345679,12345680"

Inputs: activity_ids (required), unit. Returns: result

find_similar_activitiesA
Read-only

Find activities similar to a reference activity.

Finds activities matching specified criteria:

  • type: Same activity type (running, cycling, etc.)

  • distance: Similar distance (±20%)

  • elevation: Similar elevation gain (±30%)

  • duration: Similar duration (±20%)

Returns similarity scores and comparisons.

Example: criteria="type,distance"

Inputs: activity_id (required), criteria, limit, unit. Returns: result

get_activity_detailsA
Read-only

Get comprehensive details for a specific activity.

Fetch exactly the information you need about an activity with flexible detail options.

By default, includes splits, weather, HR zones, and gear. Exercise sets are only included when explicitly requested (useful for strength training).

When include_splits=True and the activity has only 1 lap, estimated km/mile splits will be computed based on average pace.

Inputs: activity_id (required), include_splits, include_weather, include_hr_zones, +3 more. Returns: result

get_activity_socialB
Read-only

Get social details for an activity (likes, comments, kudos).

Inputs: activity_id (required). Returns: result

get_performance_metricsA
Read-only

Get comprehensive performance metrics.

Includes VO2 max, hill score, endurance score, heart rate variability, and fitness age data.

Supports both single-date and date-range queries.

Inputs: date, start_date, end_date, include_vo2_max, +4 more. Returns: result

get_training_effectA
Read-only

Get training effect and progress summary.

Supports:

  1. Training effect for specific activity (provide activity_id)

  2. Progress summary over date range (provide start_date, end_date, metric)

Inputs: activity_id, start_date, end_date, metric. Returns: result

get_user_profileA
Read-only

Get comprehensive user profile with optional stats, personal records, and devices.

Inputs: include_stats, include_prs, include_devices. Returns: result

log_health_dataB

Log health data entries.

Data types:

  • body_composition: Requires data with weight, body_fat, etc.

  • blood_pressure: Requires data with systolic, diastolic

  • hydration: Requires data with volume_ml

All data should be provided as a JSON string.

Inputs: data_type (required), data (required), date. Returns: result

manage_weight_dataA

Add or delete weight entries.

Actions:

  • add: Add a new weight entry (provide weight, optionally date)

  • delete: Delete weight entries (provide weigh_in_ids)

Inputs: action (required), weight, date, weigh_in_ids. Returns: result

manage_workoutsB

Manage structured workouts.

Actions:

  • list: Get all workouts

  • get: Get specific workout by ID

  • download: Download workout file

  • upload: Upload a new workout

Inputs: action (required), workout_id, workout_data. Returns: result

query_activitiesA
Read-only

Query activities with flexible parameters and pagination support.

This unified tool supports multiple query patterns:

  1. Get specific activity: provide activity_id

  2. Get activities by date range: provide start_date and end_date (paginated)

  3. Get activities for specific date: provide date

  4. Get paginated activities: use cursor and limit

  5. Get last activity: no parameters

All queries can be filtered by activity_type (e.g., 'running', 'cycling').

Pagination: For large time ranges, use pagination to retrieve all activities:

  1. Make initial request without cursor

  2. Check response["pagination"]["has_more"]

  3. Use response["pagination"]["cursor"] for next page

Returns: JSON string with structure: { "data": { "activity": {...} // Single activity mode OR "activities": [...], // List mode "count": N }, "pagination": { // List mode only (when paginated) "cursor": "...", // Use for next page (null if no more) "has_more": true, "limit": 20, "returned": 20 }, "metadata": {...} }

Inputs: activity_id, start_date, end_date, date, +4 more. Returns: result

query_activity_metricsA
Read-only

Get activity metrics (steps, stress, etc.).

Includes steps, stress, respiration, SpO2, floors climbed, hydration, blood pressure, and body composition.

Select specific metrics to retrieve using the metrics parameter. Default: steps and stress.

Inputs: date, start_date, end_date, metrics, +1 more. Returns: result

query_challengesA
Read-only

Query challenges and badges.

Filters by status (active/available/earned) and type (badge/adhoc/virtual).

Inputs: status, challenge_type. Returns: result

query_devicesB
Read-only

Query Garmin devices.

Get comprehensive device information including last used device, primary training device, settings, solar data, and alarms.

Inputs: device_id, include_last_used, include_primary, include_settings, +2 more. Returns: result

query_gearA
Read-only

Query gear and equipment.

Get comprehensive gear information including defaults and usage stats.

Inputs: include_defaults, include_stats. Returns: result

query_goals_and_recordsA
Read-only

Get goals, personal records, and race predictions.

Returns your activity goals, personal best performances, and predicted race times based on recent training.

Inputs: include_goals, include_prs, include_race_predictions. Returns: result

query_health_summaryA
Read-only

Get comprehensive daily health snapshot with pagination support.

Includes stats, user summary, training readiness, training status, Body Battery, and Body Battery events.

Supports single date or date range queries with pagination.

Pagination: For large date ranges, use pagination:

  1. Make initial request with start_date and end_date

  2. Check response["pagination"]["has_more"]

  3. Use response["pagination"]["cursor"] for next page

Returns: JSON string with structure: { "data": { "summaries": [...], // Range mode (paginated) "count": N OR {...} // Single date mode }, "pagination": { // Range mode only "cursor": "...", "has_more": true, "limit": 30, "returned": 30 }, "metadata": {...} }

Inputs: date, start_date, end_date, cursor, +5 more. Returns: result

query_heart_rate_dataA
Read-only

Get heart rate data.

Retrieves heart rate data including resting HR, average HR, min/max values. Supports single date or date range queries.

Inputs: date, start_date, end_date, include_resting. Returns: result

query_sleep_dataA
Read-only

Get sleep data and analysis.

Retrieves sleep duration, sleep stages (deep, light, REM), sleep scores, HRV, resting heart rate, and body battery impact.

Supports single date or date range queries.

Inputs: date, start_date, end_date. Returns: result

query_weight_dataA
Read-only

Query weight data.

Get weight measurements for a specific date or date range.

Inputs: date, start_date, end_date. Returns: result

query_womens_healthA
Read-only

Query women's health data.

Data types:

  • pregnancy: Get pregnancy tracking summary

  • menstrual: Get menstrual cycle data (for specific date or date range)

Inputs: data_type (required), date, start_date, end_date. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool targets a distinct function: activities (query, details, compare, similar, period analysis, social, training effect), health data (weight, sleep, HR, activity metrics, summary, womens health, performance), and management (workouts, gear, devices, challenges, goals). No two tools have overlapping purposes, reducing ambiguity.

    Naming Consistency4/5

    Tools follow a verb_noun pattern, but the verbs vary (get, query, manage, log, analyze, compare, find). While each verb is appropriate for its operation, the mix of 'get_' and 'query_' for similar retrieval actions introduces minor inconsistency. Overall pattern is clear but not perfectly uniform.

    Tool Count4/5

    With 22 tools, the set is slightly above the typical well-scoped range (3-15) but appropriate for the breadth of Garmin Connect's capabilities. Each tool covers a distinct area without unnecessary duplication, and the number reflects the domain complexity.

    Completeness5/5

    The tool set covers all major Garmin Connect features: activity tracking (query, details, compare, similar, period analysis, social, training effect), health metrics (weight, sleep, HR, activity metrics, health summary, performance, womens health), and management (workouts, gear, devices, challenges, goals). No obvious gaps for core functionality.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers