Garmin Coach MCP Server (garmin-coach-mcp)

A Personal Health, Running, and Fitness Coach Model Context Protocol (MCP) server powered by Garmin Connect telemetry. Built on the official Python mcp SDK (FastMCP), garminconnect, garth, and Pydantic v2, this server transforms noisy, deeply nested Garmin Connect API responses into token-efficient, coach-ready Markdown and structured JSON for both local AI clients (stdio for Claude Desktop, Cursor, Antigravity, and Gemini CLI) and remote web/cloud clients (streamable-http over HTTPS with Bearer token authentication for gemini.google.com Connected Apps, Gemini Mobile, and Gemini Enterprise on Google Cloud Run).

Core Coaching Use Cases

1. Daily Readiness & Morning Check-in

   • Combines Training Readiness, Body Battery (current, charged, drained), Overnight HRV (last night average, 5-min high, 7-day average vs. baseline), Sleep stages & score, Resting Heart Rate (RHR), Stress, and yesterday's training load in a single aggregated call (get_coach_daily_briefing) to answer: "Should I execute my hard interval session today, modify the pace, or swap for a recovery jog?"

2. Deep Workout Analysis & Post-Activity Debrief

   • Inspects lap/split pacing evenness, Heart Rate Zone distribution, Power/Pace Zone compliance, elevation-adjusted effort, cadence, weather impact, and cardiac drift (%) (get_activity_details, list_recent_activities) to evaluate execution quality.

3. Longitudinal Trend & Load Management

   • Tracks Acute-to-Chronic Workload Ratio (ACWR), aerobic/anaerobic load focus, VO2 Max, Endurance/Hill scores (get_training_status_and_load), and 7-to-90 day rolling averages & first-half vs. second-half deltas for RHR, HRV, sleep, steps, stress, and training volume (get_health_trends) to detect overreaching early.

4. Adaptive Training Plans & Structured Workout Prescription

   • Synthesizes athlete biometrics, Lactate Threshold HR/Pace, FTP, and zone boundaries (get_body_composition_and_biometrics, garmin://athlete/profile) with current recovery state to build periodized training plans and generate Garmin-compatible structured workouts (create_structured_workout_json) with optional direct upload to Garmin Connect Calendar.

Related MCP server: claude-garmin

System Architecture

flowchart LR
    subgraph LocalClients["Local AI Clients"]
        IDEs["Claude Desktop / Cursor / Antigravity"]
        GeminiCLI["Gemini CLI"]
        Inspector["MCP Inspector"]
    end

    subgraph RemoteClients["Remote Web & Mobile Clients"]
        GeminiWeb["gemini.google.com<br/>(Connected Apps & Mobile)"]
        GeminiEnt["Gemini Enterprise"]
    end

    subgraph Server["garmin-coach-mcp (FastMCP / Cloud Run)"]
        AuthMiddleware["BearerAuthMiddleware<br/>(Authorization: Bearer + /healthz)"]
        Tools["8 Coaching Tools<br/>(briefing, health, activities, workouts)"]
        Resources["2 MCP Resources<br/>(athlete/profile, coach/context/today)"]
        Prompts["3 Coaching Prompts<br/>(morning, debrief, weekly-plan)"]
        Normalizers["Normalizers & Pydantic v2 Models<br/>(Metric/Imperial + Hybrid Formatter)"]
        Client["GarminCoachClient"]
        Cache[("SQLite TTLCache<br/>~/.cache/garmin-coach-mcp/cache.db")]
        Auth["GarminAuthManager<br/>(garth OAuth1/OAuth2)"]
    end

    subgraph Upstream["Token Stores & External Upstream"]
        Tokens[("Local Token Store<br/>~/.garminconnect (0700)")]
        TokenB64[("GARMIN_TOKEN_BASE64<br/>(Cloud Secret Manager)")]
        GarminAPI["Garmin Connect API"]
    end

    IDEs <-->|"MCP (stdio)"| Tools
    GeminiCLI <-->|"MCP (stdio)"| Tools
    Inspector <-->|"MCP (stdio / HTTP)"| AuthMiddleware
    GeminiWeb <-->|"HTTPS streamable-http (/mcp)<br/>+ Bearer Auth"| AuthMiddleware
    GeminiEnt <-->|"HTTPS streamable-http (/mcp)<br/>+ Bearer Auth"| AuthMiddleware
    AuthMiddleware --> Tools
    IDEs -.-> Resources
    IDEs -.-> Prompts

    Tools --> Normalizers
    Resources --> Normalizers
    Normalizers --> Client
    Client <-->|"Parameterized SQL"| Cache
    Client --> Auth
    Auth <-->|"Resume / Auto-Refresh"| Tokens
    TokenB64 -.->|"Stateless Hydration (0600)"| Tokens
    Auth <-->|"HTTPS"| GarminAPI

Installation & Setup

Prerequisites

• Python 3.11+

• uv (recommended) or standard python3 -m venv + pip

• A Garmin Connect account

Option A: One-Click Install (./install.sh or .\install.ps1) — Recommended

Run the interactive one-click installer from the repository root:

Linux / macOS / WSL (Bash):

cd /path/to/GarminMCP
./install.sh

Windows (PowerShell 5.1+ / PowerShell 7+):

cd C:\path\to\GarminMCP
.\install.ps1

Both ./install.sh and .\install.ps1 automate the complete 5-stage setup workflow:

1. [1/5] System Requirements Check: Verifies Python >= 3.11 (via python3/python/py -3 or uv).

2. [2/5] Virtual Environment & Dependencies: Creates .venv and installs garmin-coach-mcp in editable mode with dev/test dependencies (uv pip install -e ".[dev]" or .venv/bin/pip / .venv\Scripts\pip.exe install -e ".[dev]"), then verifies garmin-coach-mcp --help.

3. [3/5] Interactive Garmin Connect Login (MFA/2FA): Runs garmin-coach-mcp auth (or prompts whether to reuse existing tokens if already present in ~/.garminconnect).

4. [4/5] OAuth Token & Permission Verification: Confirms non-empty OAuth token files exist in your token directory (with strict 0700 directory / 0600 file permissions on POSIX systems).

5. [5/5] Optional Live Account Verification & MCP Config Output: Optionally runs garmin-coach-mcp verify to fetch your Garmin athlete profile and prints ready-to-copy MCP registration snippets for Claude Desktop / Cursor / Antigravity (~/.gemini/config/mcp_config.json) and Gemini CLI (gemini mcp add garmin-coach ...) using your machine's resolved paths.

Installer CLI Flags

Option B: Manual Installation (uv or pip)

Linux / macOS / WSL:

cd /path/to/GarminMCP

# Using uv (recommended):
uv venv
uv pip install -e ".[dev]"

# Or using standard Python venv + pip:
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e ".[dev]"

Windows (PowerShell):

cd C:\path\to\GarminMCP

# Using uv (recommended):
uv venv
uv pip install -e ".[dev]"

# Or using standard Python venv + pip:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\pip.exe install --upgrade pip
.\.venv\Scripts\pip.exe install -e ".[dev]"

Verify the CLI entrypoint is installed and responsive:

# Cross-platform via uv:
uv run garmin-coach-mcp --help

# Or directly via virtualenv binary (Linux / macOS / WSL):
.venv/bin/garmin-coach-mcp --help

# Or directly via virtualenv binary (Windows PowerShell):
.\.venv\Scripts\garmin-coach-mcp.exe --help

Authentication & MFA / 2FA Bootstrap Guide

Garmin Connect uses garth (OAuth1 + OAuth2) and frequently challenges logins with 2FA / MFA or Cloudflare protections. Because MCP servers run headlessly over stdio, interactive MFA prompts during an active agent tool call would hang stdio transport.

garmin-coach-mcp solves this with a two-stage authentication lifecycle:

Step 1: One-Time Interactive Token Bootstrap (Recommended for All Users & MFA Accounts)

Run the built-in interactive authentication command once in your terminal:

uv run garmin-coach-mcp auth

Or specify a custom email and token directory:

uv run garmin-coach-mcp auth --email your-email@example.com --token-dir ~/.garminconnect

1. You will be prompted for your Garmin Connect email and password (hidden input) if not already set in the environment.

2. If your account has 2FA / MFA enabled, you will be prompted interactively in your terminal for the one-time verification code sent via SMS or email.

3. Upon success, garth saves oauth1_token.json and oauth2_token.json to ~/.garminconnect (with 0700 directory permissions).

4. During all future headless MCP server runs, GarminAuthManager automatically resumes from ~/.garminconnect and refreshes short-lived OAuth2 tokens using the long-lived OAuth1 token (~1 year validity) without storing your raw password or re-prompting for MFA.

Step 2: Verify Saved OAuth Tokens & Account Access (garmin-coach-mcp verify)

After authenticating, verify your saved tokens and perform a live read check of your Garmin athlete profile:

uv run garmin-coach-mcp verify
# or with a custom token directory:
uv run garmin-coach-mcp verify --token-dir ~/.garminconnect

garmin-coach-mcp verify checks that your token files exist in ~/.garminconnect, connects to Garmin Connect, and prints a summary of your connected athlete name, configured unit system (metric / imperial), and key physiological anchors (Max HR, Resting HR, VO2 Max).

Step 3: Headless Environment Variable Fallback (Non-MFA Accounts Only)

If your account does not require interactive 2FA, you can optionally provide credentials via environment variables (see .env.example). Upon first login, tokens are still persisted to GARMIN_TOKEN_DIR for subsequent calls.

Environment Variables Reference

Ready-to-Copy MCP Client Configurations

Pre-built configuration files are available in examples/:

• examples/uv_mcp_config.json

• examples/gemini_cli_settings.json

• examples/mcp_config.json

1. Claude Desktop / Cursor / Antigravity (uv Configuration)

Add the garmin-coach entry to your MCP client configuration (e.g., ~/.gemini/config/mcp_config.json or claude_desktop_config.json; see examples/uv_mcp_config.json):

{
  "mcpServers": {
    "garmin-coach": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/GarminMCP",
        "run",
        "garmin-coach-mcp"
      ],
      "env": {
        "GARMIN_TOKEN_DIR": "~/.garminconnect",
        "GARMIN_CACHE_DIR": "~/.cache/garmin-coach-mcp",
        "GARMIN_CACHE_TTL": "900",
        "GARMIN_UNITS": "metric"
      }
    }
  }
}

2. Gemini CLI (~/.gemini/settings.json)

Merge the following block into your ~/.gemini/settings.json (see examples/gemini_cli_settings.json):

{
  "mcpServers": {
    "garmin-coach": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/GarminMCP",
        "run",
        "garmin-coach-mcp"
      ],
      "env": {
        "GARMIN_TOKEN_DIR": "~/.garminconnect",
        "GARMIN_CACHE_DIR": "~/.cache/garmin-coach-mcp",
        "GARMIN_CACHE_TTL": "900",
        "GARMIN_UNITS": "metric"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

3. Direct Virtualenv Binary Configuration (examples/mcp_config.json)

If you prefer invoking the virtualenv entrypoint binary directly without uv run:

{
  "mcpServers": {
    "garmin-coach": {
      "command": "/path/to/GarminMCP/.venv/bin/garmin-coach-mcp",
      "args": [],
      "env": {
        "GARMIN_TOKEN_DIR": "~/.garminconnect",
        "GARMIN_CACHE_DIR": "~/.cache/garmin-coach-mcp",
        "GARMIN_CACHE_TTL": "900",
        "GARMIN_UNITS": "metric"
      }
    }
  }
}

Using with gemini.google.com (Web Client) & Google Cloud Run

1. How It Works

Unlike local desktop agents (Claude Desktop, Cursor, Antigravity, or Gemini CLI) that spawn an MCP subprocess on your workstation over stdio, gemini.google.com (Connected Apps) and Gemini Enterprise execute in Google's cloud and cannot spawn local processes on your laptop. Instead, they connect to remote MCP servers over HTTPS using the MCP streamable-http transport (/mcp endpoint) protected by authentication headers.

garmin-coach-mcp includes first-class support for stateless cloud deployments:

• garmin-coach-mcp export-tokens & GARMIN_TOKEN_BASE64: Packages your locally bootstrapped oauth1_token.json and oauth2_token.json into a single Base64 secret string so stateless containers (such as Google Cloud Run) can hydrate your Garmin session in memory/tmpfs without interactive MFA prompts or persistent disks.

• --transport streamable-http: Serves the MCP Streamable HTTP protocol at /mcp alongside an unauthenticated container liveness endpoint at GET /healthz.

• BearerAuthMiddleware (--auth-token / GARMIN_MCP_AUTH_TOKEN): Protects your telemetry endpoint with constant-time (hmac.compare_digest) Bearer token verification (Authorization: Bearer <token>).

2. Step 1 — Bootstrap MFA Locally & Export Portable Token Bundle

First, complete interactive Garmin login (including any SMS/email MFA challenge) on your local machine and export the resulting garth OAuth1/OAuth2 tokens into a Base64 bundle:

# 1. Authenticate interactively once on your workstation
garmin-coach-mcp auth

# 2. Export the OAuth1 + OAuth2 token bundle as a Base64 string
garmin-coach-mcp export-tokens > garmin_token_b64.txt

Security Note: garmin_token_b64.txt grants access to your Garmin Connect account for up to ~1 year (the lifetime of the OAuth1 refresh token). Store it in Secret Manager and delete the local text file once uploaded.

3. Step 2 — Option A: Deploy to Google Cloud Run (Recommended)

Deploying to Google Cloud Run gives you a serverless, auto-scaling HTTPS endpoint with zero idle cost (scales to zero when not in use) backed by the included Dockerfile.

1. Store Secrets in Google Cloud Secret Manager

export PROJECT_ID="your-gcp-project-id"
export REGION="us-central1"

# Generate a strong random Bearer token for MCP client authentication
openssl rand -hex 32 > mcp_auth_token.txt

# Create secrets in Google Cloud Secret Manager
gcloud secrets create garmin-token-b64 \
  --project="$PROJECT_ID" \
  --replication-policy="automatic" \
  --data-file=garmin_token_b64.txt

gcloud secrets create garmin-mcp-auth-token \
  --project="$PROJECT_ID" \
  --replication-policy="automatic" \
  --data-file=mcp_auth_token.txt

# Clean up temporary local secret files
rm -f garmin_token_b64.txt

2. Build & Deploy to Cloud Run

gcloud run deploy garmin-coach-mcp \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --source . \
  --port 8080 \
  --allow-unauthenticated \
  --min-instances=0 \
  --max-instances=2 \
  --set-env-vars="GARMIN_MCP_TRANSPORT=streamable-http,GARMIN_UNITS=metric,GARMIN_TOKEN_DIR=/tmp/.garminconnect,GARMIN_CACHE_DIR=/tmp/.cache/garmin-coach-mcp" \
  --set-secrets="GARMIN_TOKEN_BASE64=garmin-token-b64:latest,GARMIN_MCP_AUTH_TOKEN=garmin-mcp-auth-token:latest"

(Note: --allow-unauthenticated at the Cloud Run ingress layer allows gemini.google.com to reach the HTTPS URL directly, while BearerAuthMiddleware inside garmin-coach-mcp enforces Authorization: Bearer <token> on every MCP request.)

3. Verify Your Cloud Run Deployment

export SERVICE_URL="https://garmin-coach-mcp-xxxxxxxxxx-uc.a.run.app"
export GARMIN_MCP_AUTH_TOKEN="$(cat mcp_auth_token.txt)"

# 1. Verify container health check (returns 200 OK JSON without auth)
curl -sS "$SERVICE_URL/healthz"
# -> {"status":"ok","service":"garmin-coach-mcp","version":"0.1.0"}

# 2. Verify unauthenticated requests to /mcp are rejected (returns 401 Unauthorized)
curl -i -sS "$SERVICE_URL/mcp"

# 3. Verify authenticated MCP request passes Bearer auth
curl -sS -X POST "$SERVICE_URL/mcp" \
  -H "Authorization: Bearer $GARMIN_MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-check","version":"1.0"}}}'

4. Step 2 — Option B: Quick Personal Testing via HTTPS Tunnel (Tailscale Funnel / Cloudflare Tunnel)

If you want to test gemini.google.com against your local workstation before deploying to Cloud Run, run garmin-coach-mcp locally in streamable-http mode bound to 127.0.0.1 and expose it via an HTTPS tunnel:

# 1. Start the MCP server locally on 127.0.0.1:8000 with Bearer auth enabled
export GARMIN_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
echo "Bearer Token: $GARMIN_MCP_AUTH_TOKEN"

garmin-coach-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --auth-token "$GARMIN_MCP_AUTH_TOKEN"

In a second terminal, expose 127.0.0.1:8000 over HTTPS using Tailscale Funnel or Cloudflare Tunnel:

# Option 1: Tailscale Funnel
tailscale funnel 8000
# -> Exposes https://<your-machine>.<your-tailnet>.ts.net/mcp

# Option 2: Cloudflare Quick Tunnel
cloudflared tunnel --url http://127.0.0.1:8000
# -> Exposes https://<random-subdomain>.trycloudflare.com/mcp

5. Step 3 — Connect in gemini.google.com

Once your HTTPS endpoint (https://<your-service-url>/mcp) is live:

1. Open gemini.google.com in your desktop browser.

2. Navigate to Settings → Connected Apps (or Extensions / MCP Servers in Gemini Advanced / Gemini Enterprise).

3. Click Add Custom MCP Server (or Connect App) and enter:

   • Name: Garmin Coach

   • Server URL / Endpoint: https://<your-service-url>/mcp

   • Transport: Streamable HTTP

   • Authentication: Bearer Token (paste your GARMIN_MCP_AUTH_TOKEN secret)

4. Save and enable the connection.

5. Automatic Mobile Propagation: Once registered under your Google account on gemini.google.com, your connected Garmin Coach MCP server automatically propagates to the Gemini mobile app (Android & iOS), allowing you to ask "How was my sleep and HRV last night, and what workout should I run today?" or "Create a 4x1km threshold workout and upload it to my Garmin watch" directly from your phone.

MCP Reference: Tools, Resources & Prompts

Every tool supports response_format: "hybrid" | "markdown" | "json" (default "hybrid"), returning both a concise human/coach-readable Markdown executive summary and a normalized Pydantic v2 JSON block.

8 MCP Tools

Example Tool Call: create_structured_workout_json

{
  "workout_name": "Threshold Cruise Intervals 4x1600m",
  "sport_type": "running",
  "description": "Warm up thoroughly, run 4x1600m at Lactate Threshold HR (Zone 4) with 90s jog recovery, then cool down.",
  "upload_to_garmin": false,
  "steps": [
    {
      "step_type": "warmup",
      "duration_type": "time",
      "duration_value": 900,
      "target_type": "heart.rate.zone",
      "target_zone_number": 2
    },
    {
      "step_type": "repeat",
      "duration_type": "iterations",
      "duration_value": 4,
      "repeat_steps": [
        {
          "step_type": "interval",
          "duration_type": "distance",
          "duration_value": 1600,
          "target_type": "heart.rate.zone",
          "target_zone_number": 4,
          "description": "Threshold pace effort"
        },
        {
          "step_type": "recovery",
          "duration_type": "time",
          "duration_value": 90,
          "target_type": "no.target",
          "description": "Easy recovery jog"
        }
      ]
    },
    {
      "step_type": "cooldown",
      "duration_type": "time",
      "duration_value": 600,
      "target_type": "heart.rate.zone",
      "target_zone_number": 1
    }
  ]
}

2 MCP Resources

3 MCP Prompts

Testing & Verification

The test suite uses 100% offline, deterministic pytest fixtures in tests/—zero live Garmin credentials or network calls are required to run unit or integration tests.

Run the Full Test Suite

uv run pytest -v

Run with Coverage Report

uv run pytest --cov=garmin_coach_mcp --cov-report=term-missing

Verify Live Garmin Connect Session (garmin-coach-mcp verify)

To confirm that your local OAuth tokens in ~/.garminconnect are valid and can read your Garmin Connect athlete profile:

uv run garmin-coach-mcp verify --token-dir ~/.garminconnect

Interactive Smoke Testing with MCP Inspector

You can inspect tools, resources, and prompts interactively using the official MCP CLI / Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/GarminMCP run garmin-coach-mcp

Or run the server in local streamable-http or sse mode (bound strictly to 127.0.0.1 by default):

uv run garmin-coach-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --auth-token "local-dev-secret"

Security & Privacy Architecture

Health and biometric telemetry is sensitive personal data. garmin-coach-mcp enforces strict security boundaries by design:

1. Restricted Token & Cache Permissions (0700 / 0600):

   • GARMIN_TOKEN_DIR (~/.garminconnect) and GARMIN_CACHE_DIR (~/.cache/garmin-coach-mcp) are created with 0o700 directory permissions, and OAuth token files (including those hydrated from GARMIN_TOKEN_BASE64) / SQLite cache files are restricted to owner-only access (0o600).

2. Constant-Time Bearer Authentication for Remote HTTP (BearerAuthMiddleware):

   • When running with --transport streamable-http or --transport sse and --auth-token / GARMIN_MCP_AUTH_TOKEN, all MCP requests require Authorization: Bearer <token> verified via hmac.compare_digest (returning 401 Unauthorized with WWW-Authenticate: Bearer on missing/invalid tokens), while GET /healthz remains available for Cloud Run liveness probes.

3. Zero Credential & Token Logging:

   • GarminAuthManager and GarminCoachClient never log passwords, MFA verification codes, GARMIN_TOKEN_BASE64 payloads, or raw OAuth1/OAuth2 session tokens in stack traces, stdout, stderr, or MCP error payloads.

4. Parameterized SQLite Queries:

   • TTLCache in src/garmin_coach_mcp/cache.py exclusively uses parameterized SQL queries (? placeholders) to prevent SQL injection across cache lookups, insertions, and prefix invalidations.

5. Local-Only Network Binding (127.0.0.1) & Non-Root Container:

   • Default transport is stdio. When running HTTP transports locally, --host binds exclusively to 127.0.0.1 by default (never 0.0.0.0), preventing unintended exposure on local networks. The Cloud Run Dockerfile runs as an unprivileged user (garmincoach, uid 10001).

6. Opt-In Upstream Writes:

   • All tools are strictly read-only except create_structured_workout_json, which defaults to upload_to_garmin=False so workouts are only pushed to Garmin Connect when explicitly requested by the user.