Garmin Training MCP
This read-only MCP server lets an AI client access Garmin Connect activity and wellness data through five tools.
List activities within up to 366 days, with pagination and metrics such as distance, duration, speed/pace, heart rate, and power.
Get a single activity’s summary plus paginated split summaries; GPS tracks and detailed samples are unsupported in v1.
Get sleep duration, stages, scores, and sleep/wake timestamps for up to 31 days.
Get overnight/weekly HRV averages, baseline, and status for up to 31 days.
Get daily steps, resting heart rate, stress, and Body Battery for up to 31 days.
Return structured statuses, warnings, missing-date information, and unavailable-field markers while preserving Garmin-local date semantics.
Provides read-only access to Garmin Connect training and wellness data through the Garmin Personal API, including activities, activity details and split summaries, sleep, HRV, and daily summaries such as steps, resting heart rate, stress, and Body Battery.
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., "@Garmin Training MCP How did my sleep and HRV look over the past 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.
Garmin Training MCP
Read your Garmin activities, sleep, HRV and daily health summaries in Codex or Claude Code. The server runs locally on macOS and uses Garmin's official Python client and the official MCP Python SDK.
This project is unofficial and is not affiliated with Garmin.
Install
You need macOS, Python 3.12 or newer, uv, and a Garmin Connect Personal API Key. The examples use Python 3.13.
Check that the PyPI package launches:
uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp --helpYou don't need to clone the repository. uvx downloads the package and dependencies
on first launch, then uses its cache. garmin-training-mcp is the package name;
garmin-mcp is the command it provides.
Related MCP server: Garmin Connect MCP Server
Connect your client
Create a key on the Garmin Personal API Key page.
Replace YOUR_GARMIN_PERSONAL_API_KEY below with your key in your local configuration.
Keep it out of Git, chat messages and shared examples.
Codex
Add this entry to ~/.codex/config.toml, or update the existing garmin-training entry:
[mcp_servers.garmin-training]
command = "uvx"
args = ["--python", "3.13", "--from", "garmin-training-mcp==0.1.1", "garmin-mcp"]
[mcp_servers.garmin-training.env]
GARMIN_PERSONAL_API_KEY = "YOUR_GARMIN_PERSONAL_API_KEY"Codex allows 60 seconds per tool call by default. If Garmin calls time out, add
tool_timeout_sec = 180 under [mcp_servers.garmin-training], before the .env
table. See the Codex timeout settings.
Claude Code and other JSON clients
Add this entry under mcpServers in your client's configuration.
Claude Code uses ~/.claude.json for user settings.
{
"mcpServers": {
"garmin-training": {
"type": "stdio",
"command": "uvx",
"args": [
"--python", "3.13",
"--from", "garmin-training-mcp==0.1.1",
"garmin-mcp"
],
"env": {
"GARMIN_PERSONAL_API_KEY": "YOUR_GARMIN_PERSONAL_API_KEY"
}
}
}
}If your client can't find uvx, run command -v uvx in Terminal and use the full
executable path as command. Keep the package name in args as shown.
Fully quit and reopen your client, then try:
Use Garmin to compare my last two runs. What was my average pace?
Use Garmin to summarize my sleep from the last seven days.
Check the results against Garmin Connect. --help confirms installation;
a successful Garmin tool call confirms authentication.
Save the key in a separate file
If you prefer to keep the key out of client configuration, run:
uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp setupThe prompt hides your input and saves the key to:
~/Library/Application Support/garmin-training-mcp/personal-api-keyUse the client examples above with the env block or .env table removed.
An environment key overrides this file; an empty value is an error.
Available tools
Tool | Returns |
| Activities in a date range, with distance, duration, speed, HR and power where available |
| Activity metrics and a page of split summaries |
| Sleep duration, stages, scores and timestamps |
| Overnight and weekly HRV summaries, baseline and status |
| Steps, resting HR, stress and Body Battery |
Fields depend on what Garmin provides for your account and device. Missing data isn't zero. Split summaries may group several splits. GPS tracks, detailed samples and training readiness are unavailable in v1.
Dates use Garmin's calendar dates. Wellness queries accept up to 31 days; activity queries accept up to 366 days. The server returns speed in meters/second, which the AI client can convert to pace. See the capability matrix for coverage and the reference for units, date handling and pagination.
Privacy
The server reads Garmin data and caches bearer tokens locally. It writes no health
data files or telemetry. Keys and tokens are stored as plaintext with owner-only
permissions, outside the repository. The credential directory has mode 700 and
its files have mode 600. Keys in client configuration also need restricted access.
Your AI client can send retrieved health data to its provider and retain it in chat history. Local backups or sync tools may also copy credential files. Review your client's privacy settings. See the security audit for the reviewed controls and limitations.
Test and troubleshoot
For a live check, choose a date with synced activity and wellness data:
uvx --python 3.13 --from garmin-training-mcp==0.1.1 garmin-mcp check --date YYYY-MM-DDThe check prints availability counts and statuses. It needs a saved key file or a
key available in Terminal; Terminal doesn't inherit a key from your client's env block.
An empty date result can mean there is no data for that day.
Problem | What to check |
Server won't start | Run |
| Set the key in client configuration or run |
| Replace an expired or revoked key, then restart. |
| Wait for the reported retry delay before trying again. |
Missing records | Check the date and Garmin Connect sync status. |
The reference covers all error codes.
Updates and development
To upgrade, change the version in your client's args, run --help with that
version, and restart the client. Keep your existing credentials.
For local development, locked dependencies, tests and removal instructions, see
the reference.
uvx resolves dependencies separately from the project's uv.lock.
License
MIT. Dependencies retain their own licenses.
Available Tools
5 toolsget_activityARead-onlyIdempotent
Get summary plus one page of feature/group split summaries, not guaranteed laps.
activity_id is a positive decimal string. Samples/GPS are unsupported in v1: setting either include flag returns an explicit unsupported error. No location data is returned. Follow pagination.next_offset to retrieve more split summaries.
Inputs: activity_id (required), include_gps, split_limit, split_offset, +1 more. Returns: status, records, end_date, timezone, +6 more
get_daily_summaryARead-onlyIdempotent
Daily steps, Garmin resting HR field (bpm), stress and Body Battery if present.
Inclusive ISO range <=31 days, end defaults to start. Garmin restingValue may fall back to absolute minimum HR. Stress/Body Battery retain Garmin's scale.
Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more
get_hrvARead-onlyIdempotent
Reported overnight/weekly HRV averages and optional Garmin baseline/status.
Inclusive ISO range <=31 days, end defaults to start. Values retain Garmin's scale; units and sleep-start/wake-date association need live account verification.
Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more
get_sleepARead-onlyIdempotent
Sleep duration/stages in seconds, reported score components and window times.
Inclusive ISO range <=31 days, end defaults to start. Garmin calendarDate is preserved; wake-date versus sleep-start-date association requires live verification.
Inputs: start_date (required), end_date. Returns: status, records, end_date, timezone, +6 more
list_activitiesARead-onlyIdempotent
List one activity page (max 100) within <=366 inclusive Garmin-local dates.
sport is a parent activity type key, e.g. running or cycling, not a subtype. Units: meters, seconds, m/s, bpm, watts. Follow pagination.next_offset.
Inputs: end_date (required), start_date (required), limit, sport, +1 more. Returns: status, records, end_date, timezone, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct resource: activity listing, single-activity detail, sleep, HRV, and daily summary. The only mild overlap is that get_daily_summary, get_sleep, and get_hrv all return daily wellness data, but the descriptions make the boundaries clear (steps/stress vs. sleep stages vs. HRV averages). list_activities vs. get_activity is a standard, unambiguous list/detail pair.
All five names follow the same snake_case verb_noun pattern (list_activities, get_activity, get_sleep, get_hrv, get_daily_summary). The singular/plural distinction (list_activities vs. get_activity) matches the collection-vs-single semantics rather than breaking the convention.
Five focused read-only tools is a lean but defensible scope for a Garmin data server, and each tool earns its place. It sits at the thin end of the ideal 3-15 range given the breadth of the Garmin domain, but nothing is redundant or filler.
The read surface covers activities, sleep, HRV, and daily wellness, but notable gaps remain: workout/course data, training status/readiness, stress-only detail, body composition, and device info are absent. Activity samples/GPS are explicitly unsupported and lap retrieval is not guaranteed, creating potential dead ends for agents wanting intra-activity detail.
Maintenance
Related MCP Connectors
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
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.
Read WHOOP recovery, sleep, cycles, workouts and body measurements.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides read access to Garmin Connect health and training data (sleep, heart rate, stress, HRV, activities) and supports writes like creating workouts, editing activities, and exporting files.1,323 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to Garmin Connect health, activity, profile, and device data through local stdio or streamable HTTP transports for MCP clients.MIT
- AlicenseNot gradedqualityCmaintenanceGives any MCP client local access to Garmin Connect sleep and nap data, recovery and Body Battery, training readiness and load, running tolerance, VO2 Max, race predictions, gear mileage and running summaries. It runs over stdio or Streamable HTTP and includes a credential-free demo mode with fictional sample data.2MIT
- AlicenseNot gradedqualityBmaintenanceConnects a user's own Garmin data to compatible AI clients through Garmin's official Personal API, running locally over stdio with read-only access and no Garmin username or password.1MIT