Skip to main content
Glama

garmin-mcp

WARNING

This project is entirely vibe-coded. This line is the only line written by a human in the entire codebase.

A local MCP server that gives AI assistants read-only access to your Garmin Connect health and activity data. It is built on the community garminconnect library, so it uses your normal Garmin account login. There is no official Garmin API key involved.

Everything runs on your machine. Your credentials are only used by garmin-mcp login; only session tokens are stored (~/.garmin-mcp/garmin_tokens.json, mode 0600).

What you can ask

Activities (runs, rides, swims, strength, ... with splits, laps, HR/power zones, weather, gear, GPS file export), sleep, heart rate, resting HR, HRV, stress, Body Battery, SpO2, respiration, steps, floors, intensity minutes, hydration, weight and body composition, blood pressure, training readiness/status, VO2 max, race predictions, endurance and hill score, lactate threshold, FTP, devices, goals, badges, and more (about 260 read methods in total).

Related MCP server: garmin-mcp

Install

Requires macOS/Linux with uv (brew install uv).

git clone <this repo> garmin-mcp && cd garmin-mcp
uv sync
uv run garmin-mcp login      # email, password, MFA code if enabled
uv run garmin-mcp status     # verify

Connect it to a client

Claude Desktop (stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/garmin-mcp", "garmin-mcp", "serve"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "garmin-mcp": {
            "type": "local",
            "command": ["uv", "run", "garmin-mcp", "serve"],
            "enabled": true,
            "environment": {
                "UV_WORKING_DIR": "/absolute/path/to/garmin-mcp"
            }
        }
    }
}

Claude Code / others

claude mcp add garmin -- uv run --directory /absolute/path/to/garmin-mcp garmin-mcp serve

Local HTTP server

uv run garmin-mcp serve --transport http --port 8765     # http://127.0.0.1:8765/mcp

The HTTP endpoint has no authentication and binds to 127.0.0.1 by default. Anything on your machine can read your Garmin data through it. Don't expose it to a network.

Tools

Two toolsets (serve --toolset core|all):

Toolset

What you get

core (default)

About 60 curated tools for the common data, plus garmin_list_methods and garmin_call to discover and run any other read method. Keeps the tool list small for clients that struggle with hundreds of tools.

all

Every read method registered as its own tool (about 260).

Always available: get_today (today's date in your Garmin timezone), garmin_api_get (raw GET against any Garmin Connect API path), and download_activity (saves a TCX/GPX/KML/CSV or original FIT zip to ~/.garmin-mcp/downloads and returns the path).

Only read methods are exposed. Nothing can create, edit or delete data on your Garmin account.

Large responses (e.g. a full day of per-minute heart rate, or an activity's chart data) are automatically downsampled to fit --max-chars (default 100000), and the result says so; ask for a shorter range to get full resolution.

Configuration

Variable

Default

Purpose

GARMIN_MCP_TOKENSTORE

~/.garmin-mcp

Where session tokens live

GARMIN_MCP_DOWNLOAD_DIR

<tokenstore>/downloads

Where download_activity writes

GARMIN_IS_CN

unset

Set to true for Garmin China accounts

GARMIN_EMAIL, GARMIN_PASSWORD

unset

Optional: used by login instead of prompting, and by the server as a fallback if no tokens exist (accounts without MFA only)

Tokens refresh automatically. If Garmin rejects them, tools return an error asking you to run garmin-mcp login again. garmin-mcp logout deletes the saved tokens.

Development

uv run pytest
uv run ruff check . && uv run ruff format .

Tests use a fake Garmin client and exercise the real MCP protocol (in-memory and over stdio); they need no account.

Notes

  • This relies on unofficial endpoints and may break if Garmin changes them. Logging in too often can get you rate limited, which is why tokens are reused.

  • Not affiliated with Garmin.

Available Tools

62 tools
count_activitiesB
Read-only

Return total number of activities for the current user account. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

download_activityA
Idempotent

Download an activity's raw file (GPS track, sensor data) to the local download directory and return its path. Reads from Garmin; only writes a local file.

Inputs: activity_id (required), format. Returns: result

garmin_api_getA
Read-only

Raw GET against the Garmin Connect API for endpoints that have no dedicated tool. Read-only; the path must not contain a query string (use params).

Inputs: path (required), params. Returns: result

garmin_callA
Read-only

Run any read-only Garmin Connect data method by name (see garmin_list_methods).

Inputs: method (required), arguments. Returns: result

garmin_list_methodsA
Read-only

List every read-only Garmin Connect data method runnable with garmin_call, with parameters and description. Use it to discover data without a dedicated tool (golf, nutrition, gear, ECG, women's health, calendar, courses, ...).

Inputs: query. Returns: result

get_activitiesA
Read-only

Return a page of activities, newest first, optionally filtered by type. :param start: Starting activity offset, where 0 means the most recent activity :param limit: Number of activities to return :param activitytype: (Optional) Filter activities by type :param activitysubtype: (Optional) Filter activities further by sub-type. :return: List of activities from Garmin. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: limit, start, activitytype, activitysubtype. Returns: result

get_activities_by_dateA
Read-only

Return activities between two dates, optionally filtered by type. :param startdate: String in the format YYYY-MM-DD :param enddate: (Optional) String in the format YYYY-MM-DD :param activitytype: (Optional) Type of activity you are searching Possible values are [cycling, running, swimming, multi_sport, fitness_equipment, hiking, walking, other] :param sortorder: (Optional) sorting direction. By default, Garmin uses descending order by startLocal field. Use "asc" to get activities from oldest to newest. :return: list of JSON activities. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate, sortorder, activitytype. Returns: result

get_activityB
Read-only

Return activity summary, including basic splits. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_detailsC
Read-only

Return activity details. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required), maxpoly, maxchart. Returns: result

get_activity_exercise_setsC
Read-only

Return activity exercise sets. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_gearC
Read-only

Return the gear linked to an activity. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_hr_in_timezonesC
Read-only

Return the time spent in each heart rate zone during an activity. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_power_in_timezonesC
Read-only

Return the time spent in each power zone during an activity. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_splitsC
Read-only

Return activity splits. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_split_summariesC
Read-only

Return activity split summaries. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_typed_splitsB
Read-only

Return typed activity splits. Contains similar info to get_activity_splits, but for certain activity types (e.g., Bouldering), this contains more detail. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_activity_typesB
Read-only

Return all activity types and their parent types. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_activity_weatherC
Read-only

Return activity weather. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: activity_id (required). Returns: result

get_blood_pressureC
Read-only

Return blood pressure by day for 'startdate' format 'YYYY-MM-DD' through enddate 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate. Returns: result

get_body_batteryC
Read-only

Return body battery values by day for 'startdate' format 'YYYY-MM-DD' through enddate 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate. Returns: result

get_body_battery_eventsA
Read-only

Return body battery events for date 'cdate' format 'YYYY-MM-DD'. The return value is a list of dictionaries, where each dictionary contains event data for a specific event. Events can include sleep, recorded activities, auto-detected activities, and naps. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_body_compositionB
Read-only

Return available body composition data for 'startdate' format 'YYYY-MM-DD' through enddate 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate. Returns: result

get_cycling_ftpB
Read-only

Return cycling Functional Threshold Power (FTP) information. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_daily_heart_rate_statsB
Read-only

Return resting / min / max heart rate per day. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end (required), start (required). Returns: result

get_daily_stepsC
Read-only

Fetch available steps data 'start' and 'end' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end (required), start (required). Returns: result

get_daily_stress_statsB
Read-only

Return overall stress level and stress durations per day. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end (required), start (required). Returns: result

get_daily_summariesB
Read-only

Return full daily summaries for a date range in one call. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end (required), start (required). Returns: result

get_device_last_usedA
Read-only

Return the device that synced last. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_devicesB
Read-only

Return available devices for the current user account. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_earned_badgesA
Read-only

Return all earned badges for the current user. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_endurance_scoreA
Read-only

Return endurance score by day for 'startdate' format 'YYYY-MM-DD' through enddate 'YYYY-MM-DD'. Using a single day returns the precise values for that day. Using a range returns values aggregated per aggregation period (weekly by default; the web app uses daily for its 4- and 12-week reports). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate, aggregation. Returns: result

get_fitnessage_dataB
Read-only

Return Fitness Age data for current user. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_floorsB
Read-only

Fetch available floors data 'cDate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_goalsA
Read-only

Return goals by status (active, future or past). :param status: Status of goals (valid options are "active", "future", or "past") :type status: str :param start: 1-based index of the first goal to retrieve :type start: int :param limit: Pagination limit when retrieving goals :type limit: int :return: list of goals in JSON format. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: limit, start, status. Returns: result

get_heart_ratesC
Read-only

Fetch available heart rates data 'cDate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_hill_scoreC
Read-only

Return hill score by day from 'startdate' format 'YYYY-MM-DD' to enddate 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: startdate (required), enddate. Returns: result

get_hrv_dataB
Read-only

Return HRV (Heart Rate Variability) data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_hydration_dataA
Read-only

Return available hydration data 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_intensity_minutes_dataB
Read-only

Return available Intensity Minutes data 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_lactate_thresholdB
Read-only

Return running lactate threshold information, including heart rate, power, and speed. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: latest, end_date, start_date, aggregation. Returns: result

get_last_activityB
Read-only

Return the most recent activity. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_lifetime_totalsA
Read-only

Return lifetime totals (distance, steps, calories, active days, ...). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_max_metricsC
Read-only

Return available max metric data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_personal_recordC
Read-only

Return personal records for current user. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: months, include_history. Returns: result

get_progress_summary_between_datesA
Read-only

Return progress totals (distance, duration, ...) between two dates. :param startdate: String in the format YYYY-MM-DD :param enddate: String in the format YYYY-MM-DD :param metric: metric to be calculated in the summary: "elevationGain", "duration", "distance", "movingDuration" :param groupbyactivities: group the summary by activity type :return: list of JSON activities with their aggregated progress summary. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: enddate (required), startdate (required), metric, groupbyactivities. Returns: result

get_race_predictionsB
Read-only

Return race predictions for the 5k, 10k, half marathon and marathon. Accepts either 0 parameters or all three: If all parameters are empty, returns the race predictions for the current date Or returns the race predictions for each day or month in the range provided. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: enddate, startdate. Returns: result

get_respiration_dataB
Read-only

Return available respiration data 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_rhr_dayC
Read-only

Return resting heart rate data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_sleep_dataB
Read-only

Return sleep data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_sleep_stats_weeklyB
Read-only

Return weekly sleep statistics (overallStats + per-week values). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end, weeks. Returns: result

get_spo2_dataB
Read-only

Return available SpO2 data 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_stats_and_bodyA
Read-only

Return the daily summary and body composition for a date. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_steps_dataC
Read-only

Fetch available steps data 'cDate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_stress_dataC
Read-only

Return stress data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_todayA
Read-only

Today's date (YYYY-MM-DD) in the Garmin account's timezone. Use it to resolve relative dates such as "yesterday" or "last week" before querying other tools.

Inputs: no named parameters. Returns: result

get_training_readinessC
Read-only

Return training readiness data for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_training_statusB
Read-only

Return training status data for current user. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_user_profileB
Read-only

Return the user settings (user data, units, formats, sleep times). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_user_statisticsB
Read-only

Return the profile statistics block (totals per activity type). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: no named parameters. Returns: result

get_user_summaryC
Read-only

Return user activity summary for 'cdate' format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: cdate (required). Returns: result

get_weekly_activity_statsC
Read-only

Return weekly activity aggregates (VO2 max, distance, duration, ...). (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: end (required), start (required), group_by_activity_type. Returns: result

get_weigh_insB
Read-only

Get weigh-ins between startdate and enddate using format 'YYYY-MM-DD'. (Garmin Connect, read-only. Dates are YYYY-MM-DD.)

Inputs: enddate (required), startdate (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 62 tools

    Disambiguation2/5

    Many tools overlap heavily: get_daily_heart_rate_stats vs get_heart_rates vs get_rhr_day; get_daily_stress_stats vs get_stress_data; get_steps_data vs get_daily_steps; and several activity-detail variants (get_activity, get_activity_details, get_activity_splits, get_activity_typed_splits, get_activity_split_summaries). Descriptions help in places, but an agent can easily choose the wrong endpoint for the same underlying data.

    Naming Consistency3/5

    Most tools follow a get_<noun> snake_case pattern, but there are noticeable deviations: garmin_api_get, garmin_list_methods, garmin_call, download_activity, and get_today break the dominant convention. Minor inconsistencies like get_fitnessage_data and get_weigh_ins also reduce predictability.

    Tool Count2/5

    62 tools is excessive for a read-only data server, especially because many endpoints are near-duplicates and generic escape hatches (garmin_api_get, garmin_call, garmin_list_methods) already cover undocumented data. Consolidation would make the surface far easier to navigate.

    Completeness4/5

    For a read-only Garmin Connect surface, coverage is broad: daily metrics, activities, sleep, body composition, training status, devices, goals, badges, raw API access, and downloads are all present. Some niche domains rely on the generic fallback rather than dedicated tools, but there are few obvious hard dead ends.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access and query Garmin Connect health and fitness data, including sleep, HRV, training load, and activities, with an optional coaching plugin for personalized training plans.
      9 npm
      4
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query live Garmin Connect health and fitness data, including daily metrics, activities, sleep analysis, and trends via natural language.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables local, read-only access to Garmin Connect health and training data through MCP, letting assistants summarize recovery, sleep, activities, and more without uploading your data.
      24
      MIT