Skip to main content
Glama
Garmin Training MCP

Garmin Training MCP

by Morozov90

Garmin Training MCP

Read your Garmin activities, sleep, HRV and daily health summaries in Codex or Claude Code. The server runs locally on macOS and uses Garmin's official Python client and the official MCP Python SDK.

This project is unofficial and is not affiliated with Garmin.

Install

You need macOS, Python 3.12 or newer, uv, and a Garmin Connect Personal API Key. The examples use Python 3.13.

Check that the PyPI package launches:

uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp --help

You don't need to clone the repository. uvx downloads the package and dependencies on first launch, then uses its cache. garmin-training-mcp is the package name; garmin-mcp is the command it provides.

Related MCP server: Garmin Connect MCP Server

Connect your client

Create a key on the Garmin Personal API Key page. Replace YOUR_GARMIN_PERSONAL_API_KEY below with your key in your local configuration. Keep it out of Git, chat messages and shared examples.

Codex

Add this entry to ~/.codex/config.toml, or update the existing garmin-training entry:

[mcp_servers.garmin-training]
command = "uvx"
args = ["--python", "3.13", "--from", "garmin-training-mcp==0.1.1", "garmin-mcp"]

[mcp_servers.garmin-training.env]
GARMIN_PERSONAL_API_KEY = "YOUR_GARMIN_PERSONAL_API_KEY"

Codex allows 60 seconds per tool call by default. If Garmin calls time out, add tool_timeout_sec = 180 under [mcp_servers.garmin-training], before the .env table. See the Codex timeout settings.

Claude Code and other JSON clients

Add this entry under mcpServers in your client's configuration. Claude Code uses ~/.claude.json for user settings.

{
  "mcpServers": {
    "garmin-training": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python", "3.13",
        "--from", "garmin-training-mcp==0.1.1",
        "garmin-mcp"
      ],
      "env": {
        "GARMIN_PERSONAL_API_KEY": "YOUR_GARMIN_PERSONAL_API_KEY"
      }
    }
  }
}

If your client can't find uvx, run command -v uvx in Terminal and use the full executable path as command. Keep the package name in args as shown.

Fully quit and reopen your client, then try:

Use Garmin to compare my last two runs. What was my average pace?

Use Garmin to summarize my sleep from the last seven days.

Check the results against Garmin Connect. --help confirms installation; a successful Garmin tool call confirms authentication.

Save the key in a separate file

If you prefer to keep the key out of client configuration, run:

uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp setup

The prompt hides your input and saves the key to:

~/Library/Application Support/garmin-training-mcp/personal-api-key

Use the client examples above with the env block or .env table removed. An environment key overrides this file; an empty value is an error.

Available tools

Tool

Returns

list_activities

Activities in a date range, with distance, duration, speed, HR and power where available

get_activity

Activity metrics and a page of split summaries

get_sleep

Sleep duration, stages, scores and timestamps

get_hrv

Overnight and weekly HRV summaries, baseline and status

get_daily_summary

Steps, resting HR, stress and Body Battery

Fields depend on what Garmin provides for your account and device. Missing data isn't zero. Split summaries may group several splits. GPS tracks, detailed samples and training readiness are unavailable in v1.

Dates use Garmin's calendar dates. Wellness queries accept up to 31 days; activity queries accept up to 366 days. The server returns speed in meters/second, which the AI client can convert to pace. See the capability matrix for coverage and the reference for units, date handling and pagination.

Privacy

The server reads Garmin data and caches bearer tokens locally. It writes no health data files or telemetry. Keys and tokens are stored as plaintext with owner-only permissions, outside the repository. The credential directory has mode 700 and its files have mode 600. Keys in client configuration also need restricted access.

Your AI client can send retrieved health data to its provider and retain it in chat history. Local backups or sync tools may also copy credential files. Review your client's privacy settings. See the security audit for the reviewed controls and limitations.

Test and troubleshoot

For a live check, choose a date with synced activity and wellness data:

uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp check --date YYYY-MM-DD

The check prints availability counts and statuses. It needs a saved key file or a key available in Terminal; Terminal doesn't inherit a key from your client's env block. An empty date result can mean there is no data for that day.

Problem

What to check

Server won't start

Run --help, check the uvx executable path, then restart the client.

missing_credentials

Set the key in client configuration or run setup.

authentication

Replace an expired or revoked key, then restart.

rate_limited

Wait for the reported retry delay before trying again.

Missing records

Check the date and Garmin Connect sync status.

The reference covers all error codes.

Updates and development

To upgrade, change the version in your client's args, run --help with that version, and restart the client. Keep your existing credentials.

For local development, locked dependencies, tests and removal instructions, see the reference. uvx resolves dependencies separately from the project's uv.lock.

License

MIT. Dependencies retain their own licenses.

Available Tools

5 tools
get_activityA
Read-onlyIdempotent

Get summary plus one page of feature/group split summaries, not guaranteed laps.

activity_id is a positive decimal string. Samples/GPS are unsupported in v1: setting either include flag returns an explicit unsupported error. No location data is returned. Follow pagination.next_offset to retrieve more split summaries.

Inputs: activity_id (required), include_gps, split_limit, split_offset, +1 more. Returns: status, records, end_date, timezone, +6 more

get_daily_summaryA
Read-onlyIdempotent

Daily steps, Garmin resting HR field (bpm), stress and Body Battery if present.

Inclusive ISO range <=31 days, end defaults to start. Garmin restingValue may fall back to absolute minimum HR. Stress/Body Battery retain Garmin's scale.

Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more

get_hrvA
Read-onlyIdempotent

Reported overnight/weekly HRV averages and optional Garmin baseline/status.

Inclusive ISO range <=31 days, end defaults to start. Values retain Garmin's scale; units and sleep-start/wake-date association need live account verification.

Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more

get_sleepA
Read-onlyIdempotent

Sleep duration/stages in seconds, reported score components and window times.

Inclusive ISO range <=31 days, end defaults to start. Garmin calendarDate is preserved; wake-date versus sleep-start-date association requires live verification.

Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more

list_activitiesA
Read-onlyIdempotent

List one activity page (max 100) within <=366 inclusive Garmin-local dates.

sport is a parent activity type key, e.g. running or cycling, not a subtype. Units: meters, seconds, m/s, bpm, watts. Follow pagination.next_offset.

Inputs: end_date (required), start_date (required), limit, sport, +1 more. Returns: status, records, end_date, timezone, +6 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool maps to a distinct resource: activity listing, single-activity detail, sleep, HRV, and daily summary. The only mild overlap is that get_daily_summary, get_sleep, and get_hrv all return daily wellness data, but the descriptions make the boundaries clear (steps/stress vs. sleep stages vs. HRV averages). list_activities vs. get_activity is a standard, unambiguous list/detail pair.

    Naming Consistency5/5

    All five names follow the same snake_case verb_noun pattern (list_activities, get_activity, get_sleep, get_hrv, get_daily_summary). The singular/plural distinction (list_activities vs. get_activity) matches the collection-vs-single semantics rather than breaking the convention.

    Tool Count4/5

    Five focused read-only tools is a lean but defensible scope for a Garmin data server, and each tool earns its place. It sits at the thin end of the ideal 3-15 range given the breadth of the Garmin domain, but nothing is redundant or filler.

    Completeness3/5

    The read surface covers activities, sleep, HRV, and daily wellness, but notable gaps remain: workout/course data, training status/readiness, stress-only detail, body composition, and device info are absent. Activity samples/GPS are explicitly unsupported and lap retrieval is not guaranteed, creating potential dead ends for agents wanting intra-activity detail.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read access to Garmin Connect health and training data (sleep, heart rate, stress, HRV, activities) and supports writes like creating workouts, editing activities, and exporting files.
      1,323 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives any MCP client local access to Garmin Connect sleep and nap data, recovery and Body Battery, training readiness and load, running tolerance, VO2 Max, race predictions, gear mileage and running summaries. It runs over stdio or Streamable HTTP and includes a credential-free demo mode with fictional sample data.
      2
      MIT