garmin-connect-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GARMIN_PERSONAL_API_KEY | No | The Garmin Connect Personal API key itself (option C). Checked first, before GARMIN_PERSONAL_API_KEY_COMMAND and the key file. Weakest option: it lands in plaintext in the client's config file and must be edited in every client when the key expires. | |
| GARMIN_PERSONAL_API_BASE_URL | No | Set to https://personal.connectapi.garmin.cn for Garmin China accounts. | https://personal.connectapi.garmin.com |
| GARMIN_PERSONAL_API_KEY_COMMAND | No | A command whose stdout is the key (option A), e.g. "security find-generic-password -s garmin-personal-api -w" or "op read \"op://Private/Garmin/credential\"". Runs once per server start and is held in memory; it must print the key and nothing else, and a failure or empty output stops startup. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server reads one person's own Garmin Connect data through the Personal API. Everything is read-only except garmin_download_activity_file, which writes a ZIP to a path you give it.
Interpreting results:
A metric listed in metrics_unavailable, or an empty result, means Garmin returned no data: the sensor is absent from that device, the feature was not enabled, the watch was not worn, or the data has not synced. Say the data is unavailable. Never report it as zero, and never estimate it.
Garmin returns distances in meters and durations in seconds. Call garmin_get_user_profile to learn whether the user thinks in metric or statute units before presenting figures.
Dates are calendar dates in the user's local time zone, formatted YYYY-MM-DD.
The Personal API exposes no device inventory, so there is no way to list the user's watches or ask what sensors they have. Determine availability by requesting a metric and reading what comes back.
Choosing a tool:
One date, several metrics -> garmin_get_daily_health
One metric, a date range -> garmin_get_health_trend
Finding workouts -> garmin_search_activities, then garmin_get_activity with the ID
Anything not covered -> garmin_get_raw
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| garmin_search_activitiesA | Search and filter the user's recorded Garmin activities (workouts), newest first by default. Returns one page of compact activity summaries, each with an activity ID. Pass that ID to garmin_get_activity for full detail, or to garmin_download_activity_file for the original FIT/GPX file. Examples:
Pagination: when has_more is true, call again with offset=next_offset. This covers the common filters; garmin_get_raw reaches the dive-depth, bounding-box, and field-requirement filters. |
| garmin_get_activityA | Get one activity in detail by its ID, optionally with its structured workout steps. detail_level="summary" (the default) returns the ~22 fields that apply to any sport. detail_level="full" returns all available fields, which for a single activity can exceed 200 properties covering dive, golf, and other sport-specific sensors. Use garmin_search_activities to find activity IDs. |
| garmin_get_wellness_activitiesA | List automatically detected wellness activities over a date range: the low-effort movement Garmin logs without the user starting a workout, such as walks. These are distinct from recorded workouts; use garmin_search_activities for those. Each entry includes the device that recorded it. |
| garmin_download_activity_fileA | Download an activity's original file from Garmin as a ZIP and save it to disk. Garmin serves these as a ZIP archive containing the FIT file (and sometimes GPX/TCX). The ZIP is written to output_path and the tool reports the path and size; the file contents are not returned to the model. Use garmin_search_activities to find activity IDs. |
| garmin_get_daily_healthA | Get several health metrics for a single calendar date in one call. Requests each selected metric in parallel and reports which returned data. The result always lists metrics_unavailable: a metric appearing there means the sensor is absent from the device, the feature was off, the watch was not worn, or the data has not synced. It never means the measured value was zero. Metrics: summary (steps, floors, calories, intensity minutes), sleep (stages and score), heart_rate (resting and daily range), hrv (overnight heart-rate variability), spo2 (pulse ox and acclimation), fitness_age, nutrition (logged food and goals). Examples:
For one metric across many days, use garmin_get_health_trend instead. |
| garmin_get_health_trendA | Get one health metric as a series across a date range, for trends and comparisons. One metric per call keeps the response bounded. Metrics: steps, stress, hydration, daily_summaries (full daily wellness rollup), sleep (nightly summaries), hrv (daily HRV summaries), body_battery, weight (one entry per day), weight_all (every weigh-in), weight_goals. Examples:
An empty result means no data in that range, not zero values. Narrow the range if the response hits the character limit. |
| garmin_get_heart_rate_zonesA | Get the user's configured heart-rate training zones, including the boundary beats per minute for each zone. Useful for interpreting the averageHR and maxHR on activities. |
| garmin_get_user_profileA | Get the user's Garmin Connect profile settings: display name, locale, time zone, and the unit preferences that other responses are expressed in. Call this first when units matter. measurementSystem tells you whether the user thinks in metric or statute, and powerFormat, heartRateFormat, hydrationMeasurementUnit, and glucoseMeasurementUnit give the per-metric display units. Garmin returns distances in meters and durations in seconds regardless, so this is about how to present them. Note: this endpoint carries no device or sensor information. The Personal API exposes no device inventory, so which metrics a user has is discovered by requesting them; garmin_get_daily_health reports what came back. |
| garmin_get_menstrual_cycleA | Get menstrual cycle tracking data for a date. view="summary" returns the cycle summary for the date, with cycle phase and prediction context. view="day_view" returns the detailed per-day log, which can include symptoms, flow, and pregnancy-mode baby movement (kick count) entries. This data exists only when the user tracks cycles in Garmin Connect. An empty result means tracking is not enabled or no entry exists for that date, not a zero reading. |
| garmin_get_rawA | Perform an authenticated GET against any Garmin Personal API path, for endpoints and parameters the other tools do not expose. The request goes to the configured Garmin host with the bearer token applied; only the path and query are yours to set. Use it for:
Example: path="/activitylist-service/activities/search/activities", query={"activityType":"diving","lowerMaxDepth":"1800","limit":"5"} Prefer the dedicated tools when one covers the request: they format results and report metric availability. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Most tools target clearly distinct resources: activities vs. wellness activities vs. daily health vs. trends vs. profile vs. cycle tracking, and the descriptions explicitly state the boundaries (e.g. daily_health = many metrics for one day, health_trend = one metric across days). The main soft spot is garmin_get_raw, which overlaps with nearly every other tool, though it is framed as a fallback for unexposed endpoints and parameters.
Every tool follows the same garmin_verb_noun snake_case pattern (garmin_search_activities, garmin_get_activity, garmin_download_activity_file), with a consistent server prefix and verb vocabulary of get/search/download.
Ten tools is a well-scoped set for a read-only Garmin Connect integration, with one tool per major data area plus a generic escape hatch. No tool feels redundant or padded.
The read surface is broad: activities (search/detail/file download), wellness activities, sleep, HRV, body battery, weight, stress, steps, profile, and cycle tracking, with garmin_get_raw covering anything unexposed. Gaps are minor — no workout/course listing (only workout steps embedded in get_activity), and no write operations such as upload or delete, which is plausible for a read-only server but leaves a lifecycle dead end.