| name | garmin-fitness |
| description | Garmin Connect + InfluxDB fitness data MCP. Query steps, sleep, HRV, heart rate, activities; sync new data from Garmin Connect. Use when the user asks about their fitness data, training, sleep, steps, calories, or wants to sync new data from Garmin. |
| allowed_tools | ["mcp__garmin-fitness__list_metrics","mcp__garmin-fitness__query_fitness_data","mcp__garmin-fitness__query_activities","mcp__garmin-fitness__delete_data","mcp__garmin-fitness__sync_garmin"] |
Garmin Fitness MCP
Tool Routing
"what measurements/metrics do you have?" / "what data is in the DB?"
→ list_metrics() — no arguments. Returns all measurement names.
"how many steps did I get last week?" / "total steps this month" / "average heart rate over 7 days"
→ query_fitness_data — requires metric, range, aggregation. See Metric Catalog below.
"show me my recent runs/workouts/activities" / "what did I do yesterday?"
→ query_activities — requires range, optional fields, limit, activity_type.
"delete my sleep data for March" / "remove steps from last week"
→ delete_data — requires measurement, range. Always confirm with the user before calling this. Data is permanently deleted.
"sync/pull new data from Garmin" / "refresh my fitness data"
→ sync_garmin — optional start_date, end_date (YYYY-MM-DD). Without dates, syncs from the day after the latest data in DB up to today (~30 days typical). Each day takes ~2.5s due to Garmin rate-limiting. Warn the user if syncing more than 14 days.
"how far did I run this month?" / "total miles walked in March" / "total running time last week"
→ Use query_fitness_data with an Activity Field metric (distance, duration, averageSpeed, etc.) + activity_type filter + aggregation="sum". Convert meters to miles (/ 1609.34) or seconds to hours (/ 3600) as needed.
Metric Catalog
Use these metric names exactly in query_fitness_data(metric="..."). Call list_metrics() only when the user asks what measurements exist or when a metric they expect is missing from the catalog.
Daily Stats (one row per day)
| Metric | Description | Unit hint |
|---|
total_steps | Daily step count | steps |
total_burned_calories | Calories burned | kcal |
total_distance_meters | Distance traveled | meters (→ miles via / 1609.34) |
daily_step_goal | Daily step goal | steps |
highly_active_minutes | Vigorous activity | seconds (→ hours via / 3600) |
moderately_active_minutes | Moderate activity | seconds (→ hours via / 3600) |
sedentary_minutes | Sedentary time | seconds (→ hours via / 3600) |
Sleep
| Metric | Description |
|---|
total_sleep_minutes | Total time asleep |
light_sleep_minutes | Light sleep |
deep_sleep_minutes | Deep sleep |
awake_minutes | Time awake after sleep onset |
Heart Rate
| Metric | Description |
|---|
resting_heart_rate | Resting HR |
lowest_heart_rate | Minimum HR that day |
highest_heart_rate | Maximum HR that day |
Floors
| Metric | Description |
|---|
floors_ascended | Floors climbed up |
floors_descended | Floors climbed down |
HRV
| Metric | Description |
|---|
hrv_last_night_avg | Last night's HRV average |
hrv_weekly_avg | Weekly HRV average |
Activity Fields (per-activity, tagged with activityType)
Note: These metrics support activity_type filtering in query_fitness_data. Daily Stats, Sleep, Heart Rate, Floors, and HRV metrics do not have activity type tags -- activity_type is ignored for those.
| Metric | Description | Unit hint |
|---|
distance | Activity distance | meters |
duration | Activity duration | seconds (→ hours via / 3600) |
averageSpeed | Avg speed | km/h (→ mph via × 0.621371) |
maxSpeed | Max speed | km/h |
averageHR | Avg heart rate | bpm |
maxHR | Max heart rate | bpm |
steps | Steps during activity | steps |
averageRunningCadenceInStepsPerMinute | Running cadence | spm |
avgStrideLength | Average stride length | cm |
Intraday Steps
| Metric | Description |
|---|
steps | Per-timestamp step counts throughout the day |
Range Formats
Two formats are accepted:
- Relative:
now() - <duration> — e.g. 4w (4 weeks), 7d (7 days), 1d (1 day)
- Absolute:
YYYY-MM-DD..YYYY-MM-DD — e.g. 2026-01-01..2026-04-13
Examples:
- Last 4 weeks:
range="4w"
- March 2026:
range="2026-03-01..2026-03-31"
- Since Jan 1st:
range="2026-01-01..2026-04-13"
Aggregations
Pass to aggregation= in query_fitness_data:
| Value | Meaning |
|---|
sum | Total (steps, calories, distance) |
mean | Average |
min | Minimum |
max | Maximum |
count | Number of data points |
last | Most recent value |
Activity Types
Use with activity_type=["running"] etc. in query_fitness_data or query_activities. Common types: running, walking, cycling, swimming, strength_training, yoga, hiit, other. Filter by multiple: activity_type=["running", "cycling"].
Common Query Patterns
Weekly step total
query_fitness_data(metric="total_steps", range="1w", aggregation="sum")
Average sleep duration over 2 weeks
query_fitness_data(metric="total_sleep_minutes", range="2w", aggregation="mean")
→ Display as hours: divide seconds by 3600.
Resting HR trend (daily for 4 weeks)
query_fitness_data(metric="resting_heart_rate", range="4w", aggregation="mean", group_by="1d")
Recent 5 activities
query_activities(range="2w", limit=5)
Recent runs only
query_activities(range="4w", limit=10, activity_type=["running"])
Weekly calories burned
query_fitness_data(metric="total_burned_calories", range="1w", aggregation="sum")
HRV this week vs last week
query_fitness_data(metric="hrv_last_night_avg", range="1w", aggregation="mean")
query_fitness_data(metric="hrv_last_night_avg", range="2w", aggregation="mean")
Total running + walking distance in a date range
query_fitness_data(metric="distance", range="2026-01-01..2026-03-31", aggregation="sum", activity_type=["running", "walking"])
Result is in meters -- divide by 1609.34 for miles.
Total running duration this month
query_fitness_data(metric="duration", range="4w", aggregation="sum", activity_type=["running"])
Result is in seconds -- divide by 3600 for hours.
Sync Guidance
sync_garmin() without dates:
- Start: day after the latest
total_steps entry in InfluxDB, or 30 days ago if DB is empty
- End: today
- Rate: ~2.5 seconds per day (Garmin API limit)
When to run sync
- New Garmin data is not showing up → sync
- After a missed day or vacation → sync with explicit
start_date and end_date
- Before answering questions about the last few days → sync first if data seems missing
Large sync warning
If the default range would sync more than 14 days, warn the user: "This will take ~35 seconds due to Garmin rate-limiting. Continue?" Use explicit short ranges when the user only needs recent data.
Sync with explicit dates
sync_garmin(start_date="2026-04-01", end_date="2026-04-13")
Anti-Patterns
- Do NOT call
list_metrics() to check what metrics exist — the Metric Catalog in this skill lists all of them. Call list_metrics() only when the user asks "what measurements do you have?".
- Do NOT call
delete_data without explicit user confirmation. Data is permanent. Show the user what will be deleted first: "Delete all total_sleep_minutes from 2026-03-01 to 2026-03-31? This cannot be undone."
- Do NOT call
sync_garmin with no date range for large gaps — if the user asks to sync "all of March", specify start_date and end_date explicitly rather than relying on the auto-default which starts from the latest data.
- Do NOT assume the DB has recent data — if the user asks about yesterday's steps and the answer looks stale, suggest running
sync_garmin().
- Do NOT use aggregation
mean on metrics that are already daily totals (like total_steps) and then compare across different range sizes without accounting for the difference. A 4-week sum and 1-week sum need the same time base for comparison.
