Skip to main content
Glama

ownmetrics-mcp

Ask Claude, ChatGPT or any MCP-capable AI app about your own Garmin data: sleep, HRV, stress, Body Battery, heart rate, activities and more. It uses Garmin's official Personal API, runs on your own computer, and is read-only.

Unofficial project. Not affiliated with, endorsed by or supported by Garmin. "Garmin" and "Garmin Connect" are trademarks of Garmin Ltd. or its subsidiaries. Results are informational, not medical advice.

Status: v0.3 (preview). Nine data tools and five insight tools (training summaries, period comparisons, trends, training vs sleep, weekly review). FIT-file analysis is next.

What you can ask

  • "How did I sleep this week? Which night was worst, and why?"

  • "Show my HRV for the last 30 days. Is it trending down?"

  • "What were my stress and Body Battery like yesterday?"

  • "List my runs this month with distance and average pace."

  • "Break down my last long ride: power, heart rate, training effect."

  • "How has my resting heart rate changed since September?"

  • "Which month did I sleep best this year, and how much did I train that month?"

  • "Compare my sleep and training this October with last October."

  • "Do my evening tennis sessions go with worse sleep?"

  • "Give me my weekly review."

  • "Is my Garmin connection working?"

Related MCP server: Garmin MCP Server

Easiest: one-click install for Claude Desktop

  1. Create your Garmin Personal API key: sign in to Garmin Connect on the web, open Settings → Personal API, select Create Key, accept Garmin's terms, choose how long it lasts, and copy it.

  2. Download ownmetrics-mcp-<version>.mcpb from the latest release.

  3. Double-click it. Claude Desktop opens and asks to install it; paste your key when asked. Claude Desktop keeps it masked. (Already saved a key with ownmetrics-mcp auth? Leave the field blank.)

  4. Ask Claude: "Is my Garmin connection working?"

The bundle isn't signed yet, so Claude Desktop may show a warning before installing. The first start downloads a few Python packages, so it needs internet and can take a moment.

Set up for other apps (about 10 minutes)

For Claude Code, ChatGPT desktop, Cursor and other apps that support MCP servers, or if you prefer Claude Desktop's config file:

1. Install uv (one time)

uv runs Python tools without any manual setup.

  • macOS / Linux: open Terminal and run curl -LsSf https://astral.sh/uv/install.sh | sh

  • Windows: open PowerShell and run powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Create your Garmin Personal API key

  1. Sign in to Garmin Connect on the web and open Settings → Personal API.

  2. Select Create Key, read and accept Garmin's terms, and choose how long the key lasts (30 days to a year; your choice).

  3. Copy the key. Garmin shows it only once.

3. Save the key

uvx ownmetrics-mcp auth

Paste the key when asked (it stays hidden). It is checked with Garmin, then saved to ~/.config/garmin/connect-personal-api-key in your home folder. On macOS and Linux the file is readable only by you; on Windows it sits in your user profile folder, protected by your Windows account.

4. Add it to your AI app

Claude Desktop: Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "ownmetrics": {
      "command": "uvx",
      "args": ["ownmetrics-mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code:

claude mcp add ownmetrics -- uvx ownmetrics-mcp

Other apps: use command uvx with the argument ownmetrics-mcp.

Updating

uvx keeps the version it first downloaded. To move to the latest release, run uvx ownmetrics-mcp@latest --version, then restart your AI app.

Then ask: "Check my Garmin connection, then summarize my sleep and HRV for the last week."

Tools

Tool

What it returns

get_daily_overview

One day: steps, distance, floors, heart rate, stress, Body Battery, calories, intensity minutes, sleep

get_sleep

Per night: hours, deep/light/REM/awake, score, Garmin's feedback, heart rate, respiration

get_hrv

Per night: HRV last-night and weekly average, 5-minute high, status, baseline

get_stress_and_body_battery

Per day: stress level, time in each stress band, Body Battery high/low/charged/drained

get_heart_rate

One day: resting, min, max, 7-day resting average; your heart rate zones

list_activities

Activities in a date range, optionally by type, with duration, distance, heart rate

get_activity

One activity: pace, speed, power, cadence, training effect and load, splits

get_body_metrics

Weigh-ins, BMI, body fat, hydration; Pulse Ox and fitness age

get_account_status

Whether your key works, a warning in its final day, which of the data areas above respond

Insight tools do the fetching and the math in one call, over up to a year:

Tool

What it answers

training_summary

Training by week or month: sessions, hours, hours per week, evening sessions, per-sport breakdown

compare_periods

Two periods side by side: sleep, HRV, resting heart rate, stress, Body Battery, steps, training, with change and % change

recovery_correlations

Whether training goes with better or worse sleep and HRV the night after, with sample size and strength. Correlation, not cause.

trend

One metric by day, week or month, with direction (up, down or flat) and change per 30 days

weekly_review

The same review every time: this week (so far) against the same days last week and your previous 28 days, best and worst nights, and highlights from fixed rules

Sleep and HRV are dated by the morning the night ended (woke_up_on), as Garmin does. Pace is shown for running, walking and hiking; speed for other sports; distance says "not applicable" for sports like strength training or pilates.

Every field name carries its unit (resting_hr_bpm, distance_km, sleep_score_0_100). Where Garmin has no value, the field says "not recorded", never zero.

What Garmin's Personal API does not provide

  • Read-only: nothing can be sent to your watch or written to Garmin Connect.

  • Not available: training readiness, training status, acute/chronic load, VO2 max, gear and devices. The tools say "not provided by Garmin's Personal API" rather than guessing.

  • Data tools cover up to 90 days per question and insight tools up to 366 days; the server splits requests to stay within Garmin's own limits.

Privacy and security

  • Runs on your computer. Talks only to Garmin. No database, no telemetry.

  • Your AI app sends tool results to its AI model, under that provider's terms.

  • Your key never appears in tool results, logs or errors.

  • Delete the key in Garmin Connect at any time to cut off access instantly.

Details: PRIVACY.md · THREAT_MODEL.md · Report vulnerabilities: SECURITY.md

Use of Garmin's API is subject to Garmin's terms: your key is personal to you and must not be shared.

Troubleshooting

  • "Garmin rejected your Personal API key": it expired or was deleted. Create a new one and run step 3 again. Garmin emails a reminder about a week before a key expires.

  • The AI app doesn't see the tools: restart the app fully. On macOS, if uvx isn't found, use its full path (run which uvx in Terminal) as the command.

  • Check the connection yourself: uvx ownmetrics-mcp status

How it's built

This project is built with spec-driven development. SPEC.md holds numbered requirements and the non-negotiable rules; every requirement traces to tests in TRACEABILITY.md, which CI regenerates and checks on every change. Contributions follow the same path: see CONTRIBUTING.md.

Built on Garmin's official connect-personal-api-python client and the Model Context Protocol Python SDK.

License

MIT

Available Tools

14 tools
compare_periodsA
Read-onlyIdempotent

I2. Compare two periods (each up to 366 days), e.g. this October vs last October: average sleep, HRV, resting heart rate, stress, Body Battery, steps and training per week, with change and % change and how many days of data each side has. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: a_end (required), b_end (required), a_start (required), b_start (required), +1 more. Returns: object

get_account_statusA
Read-onlyIdempotent

T9. Check the Garmin connection: whether the key works, granted scopes, a warning if the key expires within a day, which data areas respond, and what Garmin does not provide. Use this first when something fails. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: no named parameters. Returns: object

get_activityA
Read-onlyIdempotent

T7. Details of one activity by id: duration, distance, pace, speed, heart rate, power, cadence, training effect and load, splits and structured workout steps. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: activity_id (required). Returns: object

get_body_metricsA
Read-onlyIdempotent

T8. Body metrics over a date range: weigh-ins (kg), BMI, body fat, hydration; plus Pulse Ox (SpO2) and fitness age as of the end date. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

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

get_daily_overviewA
Read-onlyIdempotent

T1. One day's overview: steps, distance, floors, resting/min/max heart rate, stress, Body Battery, calories, intensity minutes, sleep hours and sleep score. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: date (required). Returns: object

get_heart_rateA
Read-onlyIdempotent

T5. One day's heart rate (resting, min, max, 7-day resting average) and the user's heart rate zones. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: date (required). Returns: object

get_hrvA
Read-onlyIdempotent

T3. Heart rate variability (HRV) per night over a date range: last-night average, weekly average, 5-minute high, status and personal baseline, in milliseconds. Each night is labelled woke_up_on, the morning it ended. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

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

get_sleepA
Read-onlyIdempotent

T2. Sleep per night over a date range: hours, deep/light/REM/awake minutes, sleep score, Garmin's feedback, average heart rate, respiration and sleep stress. Each night is labelled woke_up_on, the morning it ended. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

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

get_stress_and_body_batteryA
Read-onlyIdempotent

T4. Per day over a date range: average stress (0-100), minutes in each stress band, and Body Battery high, low, charged and drained. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

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

list_activitiesA
Read-onlyIdempotent

T6. List activities in a date range, newest first, optionally filtered by Garmin activity type key (e.g. running, cycling, indoor_cycling, lap_swimming, strength_training). Returns ids for get_activity. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: end (required), start (required), limit, activity_type. Returns: object

recovery_correlationsA
Read-onlyIdempotent

I3. Does training go with better or worse sleep and HRV? Over up to 366 days, pairs each day's training with the night after it: correlations with sample size and strength, plus averages for training vs rest days and evening vs earlier sessions. Can focus on one sport. Correlation is not cause; say so when answering. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: end (required), start (required), activity_type. Returns: object

training_summaryA
Read-onlyIdempotent

I1. Training totals over up to 366 days, by week or month: sessions, hours, hours per week, evening sessions, average aerobic training effect, and a per-sport breakdown. Use for 'how much did I train' questions. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: end (required), start (required), group_by. Returns: object

trendA
Read-onlyIdempotent

I4. Trend of one metric over up to 366 days, by day, week or month: the series, change per 30 days and whether it is going up, down or flat. Daily grouping adds a 7-day rolling average. Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: end (required), start (required), metric (required), group_by. Returns: object

weekly_reviewA
Read-onlyIdempotent

I5. Weekly review, the same every time: training, sleep, HRV, resting heart rate, stress and Body Battery for the Monday-to-Sunday week containing week_of (default: this week so far), against the same days last week and the previous 28 days; best and worst nights; and highlights from fixed rules. Use for 'weekly review' or 'how was my week' questions. For a general weekly review, call it once with no week_of; pass week_of only when the user names a week (e.g. 'last week'). Results are informational, not medical advice. Fields Garmin did not record say 'not recorded'; never treat them as zero.

Inputs: week_of. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 14 tools

    Disambiguation4/5

    The raw metric tools have some overlap—daily_overview includes sleep, heart rate, stress and Body Battery that also have dedicated tools—but the descriptions and time scopes (one day vs date range) make boundaries usable. The analytical tools (training_summary, trend, compare_periods, recovery_correlations, weekly_review) are clearly distinct in purpose.

    Naming Consistency4/5

    Retrieval tools follow a consistent get_/list_ noun pattern, while analytical tools use descriptive noun phrases. The mix is intentional and readable, though the analytics tools do not follow the same verb-led convention.

    Tool Count5/5

    Fourteen tools is well-scoped for a Garmin health metrics server, covering raw metrics, activity lookup, account status, and higher-level analytics without feeling bloated. Each tool has a clear domain role.

    Completeness4/5

    The read-only surface is strong: sleep, HRV, heart rate, stress, Body Battery, body metrics, activities, training summaries, trends, comparisons, correlations, and weekly reviews are all covered. Minor gaps exist for dedicated VO2 max, respiration, workout planning, or device management, but most needs can be worked around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      B
      quality
      B
      maintenance
      A read-only MCP server that lets AI agents query a user's own Garmin Connect data via Garmin's official Personal API. It exposes activities, daily wellness metrics, sleep and recovery, and body/profile data as tools for natural-language analysis.
      21
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local synchronization of Garmin activity and health data using a personal API key, then lets MCP-connected AI clients analyze training readiness and recovery with cited models and research. Supports viewing records, sleep/HRV, stress, Body Battery, and generating pre-run recommendations without hosting accounts or personal data.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives MCP clients read-only access to Garmin Connect data through Garmin's official Personal API, exposing daily metrics, sleep, activities, body composition, and related wellness endpoints via OAuth-protected remote tools.
      864 npm
      MIT