garmin-athletics-mcp
Provides read-only access to Garmin athletics and wellness data, including daily health, recovery snapshots, performance metrics, workouts, and trends from a Garmin Forerunner 55.
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-athletics-mcp How is my recovery looking today?"
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 Athletics MCP
A private, read-only Model Context Protocol server that gives local Codex and Claude Desktop sessions access to athletics and wellness data from a Garmin Forerunner 55.
Security model
Runs locally over MCP
stdio; it does not open a network port.Uses the unofficial
garminconnectpackage and can require maintenance if Garmin changes its private endpoints.Accepts Garmin credentials only through the interactive admin login command.
Stores Garmin session tokens under the current Windows user profile, never in MCP configuration.
Exposes read-only MCP tools. Login, deletion, workout upload, scheduling, and account changes are not tools.
Stores normalized records in SQLite and does not archive raw Garmin API responses.
GPS routes are intentionally not fetched, stored, or exposed.
This project provides training context, not medical advice or diagnosis.
Related MCP server: DkwtMCP
What is implemented
The server exposes these read-only tools:
get_daily_healthget_recovery_snapshotget_performance_metricslist_workoutsget_workout_details(splits and metrics only; no GPS)compare_latest_workoutget_athletics_trendsget_recent_athletics_trends
Every information request attempts a fresh Garmin fetch. Calls for the same data within 60 seconds are coalesced so a single agent response cannot hammer Garmin. If Garmin is unavailable, the response may use the timestamped local cache and includes a warning.
The Forerunner 55 provides running VO2 max, recovery time, race predictions, sleep, Body Battery, stress, heart rate, steps, calories, intensity minutes and workout data. Newer features such as HRV Status and Training Readiness are returned as unavailable when the account does not contain them; the server never fabricates substitutes.
Installation
Python 3.12 or newer is required.
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytestThis workspace already has Python 3.12, .venv, and the development dependencies installed.
First local login
Close screen-sharing or recording software before entering credentials. From PowerShell in this directory, run:
.\.venv\Scripts\garmin-athletics-admin.exe loginEnter the Garmin email, password and MFA code only in that local terminal. The command saves session tokens under:
C:\Users\dan\AppData\Local\GarminAthleticsMCP\tokensThe password and MFA code are not saved. Do not paste either into Codex, Claude, source files, MCP configuration, or chat.
Check the connection:
.\.venv\Scripts\garmin-athletics-admin.exe doctorImport all eight months of history
After login, run:
.\.venv\Scripts\garmin-athletics-admin.exe backfill --days 245 --delay 2The importer is conservative and resumable. Existing complete days are preserved, failures are reported, and rerunning the same command retries gaps. Use --force only when you intentionally want to re-fetch completed days.
Codex configuration
The repository includes .codex/config.toml. It launches this server through the project virtual environment and points it at the shared Windows-local data directory.
After login:
Restart Codex or start a new task for this trusted workspace.
Confirm the
garmin_athleticsMCP server appears.Ask:
Use Garmin Athletics to show today's health data.
The OpenAI documentation MCP installer was blocked by Windows while this project was built, so the project configuration should be verified in the live Codex UI after restart.
Claude Desktop configuration
An example entry is available at config/claude_desktop_config.example.json.
Your existing Claude configuration is:
C:\Users\dan\AppData\Roaming\Claude\claude_desktop_config.jsonPreserve its existing keys. Add the example's mcpServers object at the top level, then fully restart Claude Desktop. Do not replace the entire existing file with the example.
Useful prompts
Use Garmin Athletics to assess my recovery context today. Separate observed data from interpretation.Compare my latest run with similar runs from the previous 90 days.Show my running volume, pace and VO2 max trends for the last eight months.Show the splits and heart-rate zones for workout 123456789.
Local administration
Check paths and authentication:
.\.venv\Scripts\garmin-athletics-admin.exe doctorDelete the local SQLite database and tokens:
.\.venv\Scripts\garmin-athletics-admin.exe erase --yesDeletion is intentionally unavailable through MCP. After erasing, rerun login to reconnect.
Development verification
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m pytest -vvThe tests use mocked Garmin responses. They do not require credentials or contact Garmin.
Troubleshooting
Authentication required: rerun the local
logincommand.429 or throttling: stop retrying and wait before using
doctoragain.Unsupported metric: confirm the Forerunner 55 actually records it; the server returns an availability marker.
Cached response: inspect
source,served_at,fetched_at, andwarningin the tool result.Client cannot start server: verify the absolute Python path in the client configuration and restart the client.
See SECURITY.md and docs/ARCHITECTURE.md for the data boundary and implementation layout.
Available Tools
8 toolscompare_latest_workoutC
Compare the latest workout with median values from similar workouts.
Inputs: lookback_days.
get_athletics_trendsC
Summarize training volume, pace, wellness coverage, and available VO2 max history.
Inputs: end_date (required), start_date (required).
get_daily_healthA
Fetch sleep, heart rate, Body Battery, stress, steps, calories and related data for a day.
Inputs: day.
get_performance_metricsC
Fetch available VO2 max, recovery, race-prediction and training-status metrics.
Inputs: day.
get_recent_athletics_trendsC
Convenience trend summary for the last 7 to 366 days.
Inputs: days.
get_recovery_snapshotC
Fetch daily recovery and available performance context. Not medical advice.
Inputs: day.
get_workout_detailsA
Fetch workout splits and details without downloading GPS route data.
Inputs: activity_id (required).
list_workoutsA
List read-only normalized workout summaries in a bounded date range.
Inputs: end_date (required), start_date (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Some tools have overlapping focus: get_recovery_snapshot and get_performance_metrics both include recovery data, while get_athletics_trends and get_recent_athletics_trends are similar except for time range. However, most tools have clearly distinct targets (daily health vs workouts vs trends).
Most tools follow a consistent 'get_' or 'list_' verb+noun pattern, with 'compare_latest_workout' as a minor deviation. The naming is readable and predictable overall.
Eight tools is well-scoped for an athletics data server, covering health, recovery, performance, workouts, and trends without bloat or sparseness.
The toolset covers the core read-only analytics domain well: daily health, recovery, performance metrics, workout listings/details/comparison, and trends. It lacks advanced features like fitness age or training load, but the main workflows are supported.
Maintenance
Related MCP Connectors
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).
Garmin Connect MCP server for ChatGPT, Claude and any AI agent: list activities, download FIT file, read sleep and HRV, get training status, create workout and schedule workout in your own Garmin Connect account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Garmin Connect yourself; Cotlet does not store your password and you need no Garmin Connect API key. About the official Garmin Connect API: Yes, in part (checked 27 Oct 2026). Garmin reopened its Connect Developer Program on 21 Oct 2026. Setup and FAQ: https://cotlet.dev/integrations/garmin-api-mcp-server
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server that gives Claude Desktop access to your Garmin Connect data — daily health metrics, sleep, activities, training status, and body composition.6MIT
- AlicenseAqualityCmaintenanceLocal MCP server that connects Claude Desktop with Garmin and Apple Health data to read training and recovery, estimate heart rate and pace zones, analyze performance, and create structured workouts.22MIT
- AlicenseNot gradedqualityBmaintenanceA local, single-user, read-only MCP server that gives Claude Code access to your Garmin health and training data, exposing tools for health snapshots, training status, run details, body metrics, and training analysis.1MIT
- AlicenseNot gradedqualityCmaintenanceA local, read-only MCP server that gives Claude access to your Garmin health and training data, exposing tools for health snapshots, training status, run details, body metrics, and training analysis.MIT