ownmetrics-mcp
This is a read-only Garmin MCP server for querying your own Garmin health, sleep, activity, and body data from an AI app.
Get a one-day overview: steps, distance, floors, heart rate, stress, Body Battery, calories, intensity minutes, and sleep.
Retrieve per-night sleep data over a date range, including stages, score, feedback, heart rate, respiration, and sleep stress.
Retrieve per-night HRV data, including last-night and weekly averages, 5-minute high, status, and baseline.
Retrieve per-day stress and Body Battery data, including stress bands and Body Battery high/low/charged/drained.
Get one day’s heart rate plus heart rate zones.
List activities in a date range, optionally filtered by Garmin activity type, with IDs for details.
Get detailed data for one activity: duration, distance, pace/speed, heart rate, power, cadence, training effect/load, splits, and workout steps.
Get body metrics over a date range: weigh-ins, BMI, body fat, hydration, Pulse Ox, and fitness age.
Check Garmin connection/account status, key validity, scopes, expiry warning, and which data areas respond.
Data tools are read-only, cover up to 90 days per query, and report missing Garmin values as “not recorded,” not zero.
Provides read-only access to your own Garmin Connect data through Garmin's Personal API, including sleep, HRV, stress, Body Battery, heart rate, activities, body metrics, and account/key status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ownmetrics-mcp Check my Garmin connection, then summarize my sleep and HRV for the last week."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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.
Download
ownmetrics-mcp-<version>.mcpbfrom the latest release.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.)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 | shWindows: open PowerShell and run
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Create your Garmin Personal API key
Sign in to Garmin Connect on the web and open Settings → Personal API.
Select Create Key, read and accept Garmin's terms, and choose how long the key lasts (30 days to a year; your choice).
Copy the key. Garmin shows it only once.
3. Save the key
uvx ownmetrics-mcp authPaste 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-mcpOther 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 |
| One day: steps, distance, floors, heart rate, stress, Body Battery, calories, intensity minutes, sleep |
| Per night: hours, deep/light/REM/awake, score, Garmin's feedback, heart rate, respiration |
| Per night: HRV last-night and weekly average, 5-minute high, status, baseline |
| Per day: stress level, time in each stress band, Body Battery high/low/charged/drained |
| One day: resting, min, max, 7-day resting average; your heart rate zones |
| Activities in a date range, optionally by type, with duration, distance, heart rate |
| One activity: pace, speed, power, cadence, training effect and load, splits |
| Weigh-ins, BMI, body fat, hydration; Pulse Ox and fitness age |
| 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 by week or month: sessions, hours, hours per week, evening sessions, per-sport breakdown |
| Two periods side by side: sleep, HRV, resting heart rate, stress, Body Battery, steps, training, with change and % change |
| Whether training goes with better or worse sleep and HRV the night after, with sample size and strength. Correlation, not cause. |
| One metric by day, week or month, with direction (up, down or flat) and change per 30 days |
| 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
uvxisn't found, use its full path (runwhich uvxin Terminal) as thecommand.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
Available Tools
14 toolscompare_periodsARead-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_statusARead-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_activityARead-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_metricsARead-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_overviewARead-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_rateARead-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_hrvARead-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_sleepARead-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_batteryARead-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_activitiesARead-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_correlationsARead-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_summaryARead-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
trendARead-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_reviewARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.24MIT
- AlicenseBqualityBmaintenanceA 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.21Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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.2MIT
- AlicenseNot gradedqualityCmaintenanceGives 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 npmMIT