Skip to content
Back to search

garmin-mcp-coach

MCP server for Garmin Connect data, for Claude and ChatGPT

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/philani2020--garmin-mcp-coach/badge.svg)](/listings/philani2020--garmin-mcp-coach)

HTML

<a href="/listings/philani2020--garmin-mcp-coach"><img src="/api/listings/philani2020--garmin-mcp-coach/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Needs Python 3.10+ and [uv](https://docs.astral.sh/uv/).

git clone https://github.com/<your-username>/garmin-mcp-coach.git
cd garmin-mcp-coach
uv sync
cp .env.example .env      # paste GARMIN_PERSONAL_API_KEY

Get a key at https://connect.garmin.com/app/settings/personalApiToken. It's shown once and expires after 30, 90, 180 or 365 days. The server loads `.env` from the project folder, so the key doesn't need to go into any client config.

Test with the inspector: `npx @modelcontextprotocol/inspector uv run garmin-mcp`

> If you use this folder from both Windows and WSL, `.venv` can only belong to one of them. Set > `UV_PROJECT_ENVIRONMENT=~/.venvs/garmin-mcp-coach` on the WSL side, or uv will rebuild `.venv` > for Linux and break the Windows clients.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 209 lines
  1. # garmin-mcp-coach
  2. An MCP server that gives an AI assistant read-only access to your own Garmin Connect data
  3. (sleep, HRV, Body Battery, stress, activities and more) through the Garmin Connect Personal API.
  4. Use it with Claude (Desktop or Code) or ChatGPT to ask coaching questions about your training
  5. and recovery.
  6. ```
  7. Claude Desktop / Claude Code ── stdio ──┐
  8. ▼
  9. garmin-mcp server ──► Garmin Connect Personal API
  10. ▲
  11. ChatGPT ── HTTPS ── tunnel ── HTTP ─────┘
  12. ```
  13. ## Install
  14. Needs Python 3.10+ and [uv](https://docs.astral.sh/uv/).
  15. ```bash
  16. git clone https://github.com/<your-username>/garmin-mcp-coach.git
  17. cd garmin-mcp-coach
  18. uv sync
  19. cp .env.example .env # paste GARMIN_PERSONAL_API_KEY
  20. ```
  21. Get a key at https://connect.garmin.com/app/settings/personalApiToken. It's shown once and
  22. expires after 30, 90, 180 or 365 days. The server loads `.env` from the project folder, so the
  23. key doesn't need to go into any client config.
  24. Test with the inspector: `npx @modelcontextprotocol/inspector uv run garmin-mcp`
  25. > If you use this folder from both Windows and WSL, `.venv` can only belong to one of them. Set
  26. > `UV_PROJECT_ENVIRONMENT=~/.venvs/garmin-mcp-coach` on the WSL side, or uv will rebuild `.venv`
  27. > for Linux and break the Windows clients.
  28. ## Use with Claude
  29. Claude runs the server locally over stdio. In the examples below, replace
  30. `/path/to/garmin-mcp-coach` with the absolute path where you cloned the repo (on Windows,
  31. something like `C:\\Users\\you\\garmin-mcp-coach` in JSON).
  32. **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json` on Windows,
  33. `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
  34. ```json
  35. {
  36. "mcpServers": {
  37. "garmin": {
  38. "command": "uv",
  39. "args": ["--directory", "/path/to/garmin-mcp-coach", "run", "garmin-mcp"]
  40. }
  41. }
  42. }
  43. ```
  44. **Claude Code:**
  45. ```bash
  46. claude mcp add garmin -- uv --directory /path/to/garmin-mcp-coach run garmin-mcp
  47. ```
  48. ## Use with ChatGPT
  49. ChatGPT can't start a local process, so it can't use stdio. It connects to MCP servers over
  50. HTTPS from OpenAI's servers. To use this server you run it in HTTP mode and give it a public
  51. HTTPS URL, usually with a tunnel.
  52. ### 1. Run the server in HTTP mode
  53. Add to `.env`:
  54. ```bash
  55. GARMIN_MCP_TRANSPORT=streamable-http
  56. GARMIN_MCP_PORT=8000
  57. # Pick your own random string. Anyone who knows the full URL can read your Garmin data.
  58. GARMIN_MCP_PATH=/mcp-3f9c1e7a2b8d4c60a5e1
  59. ```
  60. Generate a random path with `python -c "import secrets; print('/mcp-' + secrets.token_hex(16))"`.
  61. Start it:
  62. ```bash
  63. uv run garmin-mcp
  64. ```
  65. It listens on `http://127.0.0.1:8000/mcp-<random>`. Leave `GARMIN_MCP_HOST` at `127.0.0.1`
  66. so only the tunnel can reach it.
  67. ### 2. Expose it over HTTPS
  68. Use either tunnel. Both need the Host header rewritten to `localhost`: the server only accepts
  69. requests addressed to localhost (DNS-rebinding protection) and rejects others with
  70. `421 Invalid Host header`.
  71. **Cloudflare Tunnel** (free, no account needed for a quick tunnel):
  72. ```bash
  73. cloudflared tunnel --url http://localhost:8000 --http-host-header localhost:8000
  74. ```
  75. **ngrok:**
  76. ```bash
  77. ngrok http 8000 --host-header=rewrite
  78. ```
  79. Each prints a public URL such as `https://random-words.trycloudflare.com`. Your MCP server URL is
  80. that address plus your path:
  81. ```
  82. https://random-words.trycloudflare.com/mcp-3f9c1e7a2b8d4c60a5e1
  83. ```
  84. Quick tunnels get a new URL every time they start. For a stable URL, use a named Cloudflare
  85. Tunnel or an ngrok static domain, and update the connector in ChatGPT if the URL changes.
  86. ### 3. Add the connector in ChatGPT
  87. Custom MCP connectors need a ChatGPT plan that supports developer mode (Plus, Pro, Business,
  88. Enterprise or Edu; on workspace plans an admin may have to allow it). The menu names below may
  89. differ slightly as OpenAI changes the UI.
  90. 1. In ChatGPT, open **Settings → Apps & Connectors → Advanced settings** and turn on
  91. **Developer mode**.
  92. 2. Back in **Apps & Connectors**, click **Create** (or **Add custom connector**).
  93. 3. Fill in:
  94. - **Name:** `Garmin`
  95. - **Description:** `Read-only access to my Garmin Connect health and training data`
  96. - **MCP Server URL:** your full tunnel URL including the path
  97. - **Authentication:** `No authentication` (the random path is the only protection; see below)
  98. 4. Tick that you trust the connector and click **Create**. ChatGPT lists the tools it found.
  99. If it reports an error, check the server and tunnel logs.
  100. 5. In a new chat, open the **+** menu, choose **Developer mode** and enable the **Garmin**
  101. connector. Then ask something like:
  102. > Look at my last 14 days of sleep, HRV and Body Battery along with my runs. Am I recovering
  103. > well enough to do intervals tomorrow?
  104. ChatGPT asks before running tools it doesn't know. All the tools except
  105. `download_activity_file` are marked read-only. That one saves a file on the machine running the
  106. server, not in ChatGPT, so it's of little use from ChatGPT.
  107. ### Security
  108. The HTTP transport has **no authentication**. Anyone who has the full URL can read your health
  109. data through your API key. To keep that risk small:
  110. - Keep `GARMIN_MCP_PATH` long and random, and don't share the URL. Change it if it leaks.
  111. - Bind to `127.0.0.1` (the default) and expose the server only through the tunnel.
  112. - Stop the tunnel when you're not using ChatGPT.
  113. - Give the Garmin API key the shortest expiry that suits you, and revoke it at
  114. https://connect.garmin.com/app/settings/personalApiToken if needed.
  115. The tunnel URL appears in your ChatGPT connector settings, and OpenAI's servers send the
  116. requests. If you need real access control, put the server behind an OAuth-capable gateway and
  117. pick OAuth as the connector's authentication.
  118. ## How auth to Garmin works
  119. 1. The server reads your Personal API key from `GARMIN_PERSONAL_API_KEY`.
  120. 2. On first use it POSTs the key to
  121. `https://personal.connectapi.garmin.com/personalapitoken-service/personal-api/personal-api-key/token`
  122. with `Authorization: ApiKey <key>` and gets back a JWT.
  123. 3. It keeps the JWT in memory and sends it as `Authorization: Bearer <jwt>`. Tokens live 24h and
  124. there are no refresh tokens, so it mints a new one when less than 1h remains, and once more
  125. on any 401.
  126. The server never writes the key to disk.
  127. ## Tools
  128. All dates are `YYYY-MM-DD` (or `today`); ranges are inclusive.
  129. | Area | Tools |
  130. |---|---|
  131. | Profile | `get_user_profile_settings`, `get_heart_rate_zones` |
  132. | Daily | `get_daily_summaries`, `get_daily_steps`, `get_daily_stress`, `get_daily_hydration`, `get_body_battery`, `get_wellness_activity_summaries` |
  133. | Sleep | `get_sleep`, `get_sleep_summaries` |
  134. | Heart | `get_heart_rate`, `get_hrv`, `get_hrv_summaries`, `get_spo2`, `get_fitness_age` |
  135. | Body / nutrition | `get_weight_measurements`, `get_weight_goals`, `get_food_logs` |
  136. | Women's health | `get_menstrual_cycle_summary`, `get_menstrual_cycle_day_view` |
  137. | Activities | `search_activities`, `get_activity`, `get_activity_workouts`, `download_activity_file` |
  138. | Escape hatch | `garmin_get`: raw GET for any endpoint without a dedicated tool |
  139. `download_activity_file` saves the original ZIP/.fit to `GARMIN_DOWNLOAD_DIR` (default
  140. `~/Downloads/garmin`) on the machine running the server.
  141. ## Environment
  142. | Variable | Default |
  143. |---|---|
  144. | `GARMIN_PERSONAL_API_KEY` | **required** |
  145. | `GARMIN_PERSONAL_API_BASE_URL` | `https://personal.connectapi.garmin.com` |
  146. | `GARMIN_DOWNLOAD_DIR` | `~/Downloads/garmin` |
  147. | `GARMIN_TIMEOUT_SECONDS` | `30` |
  148. | `GARMIN_LOG_LEVEL` | `WARNING` (logs go to stderr) |
  149. | `GARMIN_MCP_TRANSPORT` | `stdio`, or `streamable-http` for ChatGPT and other remote clients |
  150. | `GARMIN_MCP_HOST` | `127.0.0.1` (HTTP only) |
  151. | `GARMIN_MCP_PORT` | `8000` (HTTP only) |
  152. | `GARMIN_MCP_PATH` | `/mcp` (HTTP only; use a long random path when exposed) |
  153. ## Layout
  154. ```
  155. src/garmin_mcp/client.py Garmin API client, auth and .env loading
  156. src/garmin_mcp/server.py MCP tools and transport setup
  157. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.