garmin-dynamic-mcp 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- garmin_dynamic_mcp-0.2.0/.gitignore +14 -0
- garmin_dynamic_mcp-0.2.0/CHANGELOG.md +30 -0
- garmin_dynamic_mcp-0.2.0/LICENSE +21 -0
- garmin_dynamic_mcp-0.2.0/PKG-INFO +212 -0
- garmin_dynamic_mcp-0.2.0/README.md +184 -0
- garmin_dynamic_mcp-0.2.0/pyproject.toml +79 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/__init__.py +0 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/__main__.py +5 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/auth.py +107 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/catalog.json +856 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/catalog.py +145 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/catalog_overrides.json +76 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/cli.py +456 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/client.py +66 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/clients.py +340 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/clipboard.py +85 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/compact.py +152 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/errors.py +21 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/fetch.py +136 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/keystore.py +101 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/py.typed +0 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/server.py +194 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/updates.py +64 -0
- garmin_dynamic_mcp-0.2.0/src/garmin_dynamic_mcp/version.py +8 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here.
|
|
4
|
+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/) (while below 1.0, a minor bump may change behavior).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.2.0] - 2026-11-10
|
|
10
|
+
|
|
11
|
+
First public release.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- Two generic, read-only MCP tools, `list_endpoints` and `get`, over Garmin's Personal API.
|
|
16
|
+
- `garmin-dynamic-mcp setup`: opens Garmin's key page, reads the key from the clipboard, verifies it,
|
|
17
|
+
stores it in the OS keychain and configures Claude Desktop, Claude Code, Cursor, VS Code, Windsurf,
|
|
18
|
+
Gemini CLI and Codex CLI. `doctor`, `update` and `forget` commands.
|
|
19
|
+
- Endpoint catalog generated from Garmin's OpenAPI specification, with provenance (source, hash, date),
|
|
20
|
+
date-range limits read from the specification, and a daily GitHub Action that opens a pull request
|
|
21
|
+
when Garmin changes its API.
|
|
22
|
+
- Update notice (`update_available`) when a newer release exists; opt out with `GARMIN_MCP_NO_UPDATE_CHECK=1`.
|
|
23
|
+
- Automatic token exchange, activity pagination, splitting of long date ranges, field selection and
|
|
24
|
+
response truncation.
|
|
25
|
+
|
|
26
|
+
### Security
|
|
27
|
+
|
|
28
|
+
- The key is kept in the OS keychain, never in client configuration files.
|
|
29
|
+
- Only GET requests to Garmin's API host, only catalog paths, with validated parameters.
|
|
30
|
+
- Nutrition and menstrual-cycle endpoints are disabled unless `GARMIN_MCP_ENABLE_SENSITIVE=1`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Fabrizio De Bortoli
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: garmin-dynamic-mcp
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Dynamic, secure, read-only MCP server for the Garmin Connect Personal API
|
|
5
|
+
Project-URL: Homepage, https://github.com/fabriziodebortoli/garmin-dynamic-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/fabriziodebortoli/garmin-dynamic-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/fabriziodebortoli/garmin-dynamic-mcp/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Fabrizio De Bortoli
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: claude,fitness,garmin,garmin-connect,health,mcp,model-context-protocol
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: httpx>=0.27
|
|
25
|
+
Requires-Dist: keyring>=25
|
|
26
|
+
Requires-Dist: mcp<3,>=2
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
<!-- mcp-name: io.github.fabriziodebortoli/garmin-dynamic-mcp -->
|
|
30
|
+
|
|
31
|
+
# Garmin Dynamic MCP
|
|
32
|
+
|
|
33
|
+
[](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/actions/workflows/ci.yml)
|
|
34
|
+
[](https://pypi.org/project/garmin-dynamic-mcp/)
|
|
35
|
+
[](https://pypi.org/project/garmin-dynamic-mcp/)
|
|
36
|
+
[](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/LICENSE)
|
|
37
|
+
|
|
38
|
+
**The Garmin Connect MCP server that updates itself when Garmin's API changes, and keeps your key in the OS keychain.**
|
|
39
|
+
|
|
40
|
+
Ask Claude, Cursor or any MCP client about your own Garmin data: activities, steps, sleep, HRV, Body Battery, stress,
|
|
41
|
+
weight and more. It runs on your computer, with your own personal key, read-only.
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
|
|
45
|
+
1. **Install [uv](https://docs.astral.sh/uv/)** (it downloads Python and everything else by itself):
|
|
46
|
+
- Windows: `winget install astral-sh.uv`
|
|
47
|
+
- macOS: `brew install uv`
|
|
48
|
+
- Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
|
49
|
+
2. **Run the setup**, in a new terminal:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
uvx garmin-dynamic-mcp setup
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
It opens Garmin's page where you create your key: <https://connect.garmin.com/app/settings/personalApiToken>.
|
|
56
|
+
Create the key, copy it, come back to the terminal and press Enter. The setup reads the key from your
|
|
57
|
+
clipboard (or paste it, hidden), checks it with Garmin, stores it in your system keychain and configures
|
|
58
|
+
your MCP clients.
|
|
59
|
+
3. **Restart your MCP client** and ask: *"How many km did I run last week?"*
|
|
60
|
+
|
|
61
|
+
That's all. To check that everything works at any time: `uvx garmin-dynamic-mcp doctor`.
|
|
62
|
+
|
|
63
|
+
## What you can ask
|
|
64
|
+
|
|
65
|
+
Claude composes the requests itself and does the maths and the charts, so you are not limited to preset questions:
|
|
66
|
+
|
|
67
|
+
- "How many km did I run last week?"
|
|
68
|
+
- "What is my average cadence over my last ten runs?"
|
|
69
|
+
- "Chart the km I ran each day last month."
|
|
70
|
+
- "How did my sleep and HRV change over the last 90 days?"
|
|
71
|
+
- "Which weeks had the highest training load this year?"
|
|
72
|
+
|
|
73
|
+
## Supported clients
|
|
74
|
+
|
|
75
|
+
`setup` finds the clients installed on your machine and configures them. For anything else it prints the snippet to paste.
|
|
76
|
+
|
|
77
|
+
| Client | Configured by `setup` |
|
|
78
|
+
|---|---|
|
|
79
|
+
| Claude Desktop | yes (config file) |
|
|
80
|
+
| Claude Code | yes (`claude mcp add`, user scope) |
|
|
81
|
+
| Cursor | yes (`~/.cursor/mcp.json`) |
|
|
82
|
+
| VS Code | yes (user `mcp.json`) |
|
|
83
|
+
| Windsurf / Devin Desktop | yes, when its config file exists |
|
|
84
|
+
| Gemini CLI | yes, when `~/.gemini/settings.json` exists |
|
|
85
|
+
| Codex CLI | yes (`codex mcp add`) |
|
|
86
|
+
| Anything else (Zed, ...) | prints the snippet, see [Manual configuration](#manual-configuration) |
|
|
87
|
+
|
|
88
|
+
`setup` never touches a configuration file it cannot parse as plain JSON (for example one with comments): it prints
|
|
89
|
+
the snippet instead. Before its first change to a file it saves a backup next to it.
|
|
90
|
+
|
|
91
|
+
## How it stays up to date
|
|
92
|
+
|
|
93
|
+
Garmin's Personal API is new and still growing. This server does not hard-code its endpoints:
|
|
94
|
+
|
|
95
|
+
1. Every day a GitHub Action downloads Garmin's published OpenAPI specification and compares it with the one the
|
|
96
|
+
catalog was built from.
|
|
97
|
+
2. If something changed (new endpoint, new parameter, different limit), the Action regenerates the endpoint catalog
|
|
98
|
+
and opens a pull request that lists exactly what changed.
|
|
99
|
+
3. A maintainer reviews and merges it. A release is published automatically.
|
|
100
|
+
4. Your server tells you, inside the conversation, that a new version exists. You choose when to update:
|
|
101
|
+
`uvx garmin-dynamic-mcp@latest update`, then restart your client.
|
|
102
|
+
|
|
103
|
+
The server never downloads a catalog by itself while running: what it can call is always something a human reviewed.
|
|
104
|
+
If Garmin changes the page the Action reads, it opens an issue instead of failing silently.
|
|
105
|
+
|
|
106
|
+
## Security
|
|
107
|
+
|
|
108
|
+
- **Your key stays in the OS keychain** (Windows Credential Manager, macOS Keychain, Linux Secret Service), not in a
|
|
109
|
+
JSON file. `setup` never writes it into a client configuration.
|
|
110
|
+
- **Read-only and locked down.** Only `GET` requests, only to Garmin's API host, only to paths in the catalog, with
|
|
111
|
+
validated parameters. Nothing accepts a free-form URL.
|
|
112
|
+
- **Sensitive data is off by default** (nutrition, menstrual cycle): see [Sensitive endpoints](#sensitive-endpoints).
|
|
113
|
+
- **No surprise updates.** Client configurations pin an exact version. The server only tells you when a newer one exists.
|
|
114
|
+
- **Supply chain.** Releases are built by CI and published to PyPI with trusted publishing (no stored token) and
|
|
115
|
+
attestations; GitHub Actions are pinned by commit.
|
|
116
|
+
|
|
117
|
+
Details and the threat model: [docs/security.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/security.md). To report a vulnerability: [SECURITY.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/SECURITY.md).
|
|
118
|
+
|
|
119
|
+
## Privacy
|
|
120
|
+
|
|
121
|
+
- The server runs on your computer. The key is sent only to Garmin.
|
|
122
|
+
- The only other connection it makes is a daily check of PyPI for a newer version (no data about you is sent).
|
|
123
|
+
Disable it with `GARMIN_MCP_NO_UPDATE_CHECK=1`.
|
|
124
|
+
- What you ask Claude for becomes part of your conversation, like any tool result. Consider which questions you ask.
|
|
125
|
+
- Garmin's Personal API is for accessing **your own data** with **your own key**. Garmin does not intend it for commercial
|
|
126
|
+
applications serving several users. Read [Garmin's terms](https://developer.garmin.com/gc-developer-program/personal/personal-faq/).
|
|
127
|
+
|
|
128
|
+
## Updating
|
|
129
|
+
|
|
130
|
+
When a newer version exists, the answers of the tools include an `update_available` note and Claude will tell you. To update:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
uvx garmin-dynamic-mcp@latest update
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
then restart your MCP client. Prefer not to be told? Set `GARMIN_MCP_NO_UPDATE_CHECK=1` in the server's environment.
|
|
137
|
+
|
|
138
|
+
## Troubleshooting
|
|
139
|
+
|
|
140
|
+
Run `uvx garmin-dynamic-mcp doctor` first: it checks the key, the connection to Garmin, your version and every client
|
|
141
|
+
configuration, and never prints the key.
|
|
142
|
+
|
|
143
|
+
- **"expired or was revoked"**: create a new key on Garmin and run `uvx garmin-dynamic-mcp setup` again; it replaces the old one.
|
|
144
|
+
Garmin emails you about a week before a key expires.
|
|
145
|
+
- **Claude Desktop does not start the server**: it may not see `uvx` on its PATH. `setup` writes the absolute path of
|
|
146
|
+
`uvx`; if you moved it, run `setup` again. Quit Claude Desktop completely (also from the tray or the menu bar) and reopen it.
|
|
147
|
+
- **No system keychain** (some Linux servers): `setup --allow-file-storage` stores the key in an owner-only file instead.
|
|
148
|
+
- **A long period returns fewer rows than expected**: responses are capped (below); Claude is told how to narrow the request.
|
|
149
|
+
|
|
150
|
+
## Manual configuration
|
|
151
|
+
|
|
152
|
+
If you prefer to edit the configuration yourself, add this to your client's MCP servers (the key is read from the
|
|
153
|
+
keychain, so run `setup` once with `--clients none` first):
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"mcpServers": {
|
|
158
|
+
"garmin": {
|
|
159
|
+
"command": "uvx",
|
|
160
|
+
"args": ["garmin-dynamic-mcp==0.2.0"]
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
VS Code uses the top-level key `servers` and needs `"type": "stdio"`. For Claude Code:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
claude mcp add garmin --scope user -- uvx garmin-dynamic-mcp==0.2.0
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
If you do not want to use the keychain at all, set `GARMIN_API_KEY` in the server's `env` instead. That puts the key in
|
|
173
|
+
a plain-text file, which is why `setup` does not do it.
|
|
174
|
+
|
|
175
|
+
## What it reads, and its limits
|
|
176
|
+
|
|
177
|
+
Two generic tools: `list_endpoints` (what exists, with parameters; optional `query`) and `get` (call one endpoint).
|
|
178
|
+
|
|
179
|
+
- Activities (list, details, workouts), daily summaries, steps, sleep, HRV, stress, Body Battery, heart rate, SpO2, weight,
|
|
180
|
+
hydration, heart-rate zones, fitness age, profile settings. The exact list is in
|
|
181
|
+
[`catalog.json`](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/src/garmin_dynamic_mcp/catalog.json); [docs/garmin-api-findings.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/garmin-api-findings.md) says
|
|
182
|
+
which endpoints were verified against a real account.
|
|
183
|
+
- The server renews the 24-hour token, fetches activity pages (200 per request, up to 1000 activities per answer, at most
|
|
184
|
+
20 requests), splits long date ranges where Garmin enforces a limit, lets Claude pick fields, and truncates answers at about
|
|
185
|
+
40,000 characters with a note on how to narrow the request.
|
|
186
|
+
- It does not download `.FIT` files (second-by-second data) yet, and never writes anything to Garmin or your watch.
|
|
187
|
+
|
|
188
|
+
## Sensitive endpoints
|
|
189
|
+
|
|
190
|
+
Nutrition and menstrual-cycle endpoints are in the catalog but **disabled**. To enable them set
|
|
191
|
+
`GARMIN_MCP_ENABLE_SENSITIVE=1` in the server's environment. They have not been verified against a real account.
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
uv sync
|
|
197
|
+
uv run pytest # mocked HTTP, no key needed
|
|
198
|
+
uv run ruff check . && uv run ruff format --check . && uv run mypy
|
|
199
|
+
uv run python scripts/fetch_openapi.py build/openapi.json
|
|
200
|
+
uv run python scripts/build_catalog.py build/openapi.json
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
See [CONTRIBUTING.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/CONTRIBUTING.md). Releases: [docs/releasing.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/releasing.md).
|
|
204
|
+
|
|
205
|
+
## Disclaimer
|
|
206
|
+
|
|
207
|
+
This is an independent open-source project. It is **not affiliated with, endorsed by or supported by Garmin Ltd.**
|
|
208
|
+
"Garmin" and "Garmin Connect" are trademarks of Garmin Ltd. Use of the Personal API is subject to Garmin's terms.
|
|
209
|
+
|
|
210
|
+
## License
|
|
211
|
+
|
|
212
|
+
[MIT](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/LICENSE)
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
<!-- mcp-name: io.github.fabriziodebortoli/garmin-dynamic-mcp -->
|
|
2
|
+
|
|
3
|
+
# Garmin Dynamic MCP
|
|
4
|
+
|
|
5
|
+
[](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/actions/workflows/ci.yml)
|
|
6
|
+
[](https://pypi.org/project/garmin-dynamic-mcp/)
|
|
7
|
+
[](https://pypi.org/project/garmin-dynamic-mcp/)
|
|
8
|
+
[](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/LICENSE)
|
|
9
|
+
|
|
10
|
+
**The Garmin Connect MCP server that updates itself when Garmin's API changes, and keeps your key in the OS keychain.**
|
|
11
|
+
|
|
12
|
+
Ask Claude, Cursor or any MCP client about your own Garmin data: activities, steps, sleep, HRV, Body Battery, stress,
|
|
13
|
+
weight and more. It runs on your computer, with your own personal key, read-only.
|
|
14
|
+
|
|
15
|
+
## Quick start
|
|
16
|
+
|
|
17
|
+
1. **Install [uv](https://docs.astral.sh/uv/)** (it downloads Python and everything else by itself):
|
|
18
|
+
- Windows: `winget install astral-sh.uv`
|
|
19
|
+
- macOS: `brew install uv`
|
|
20
|
+
- Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
|
21
|
+
2. **Run the setup**, in a new terminal:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
uvx garmin-dynamic-mcp setup
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
It opens Garmin's page where you create your key: <https://connect.garmin.com/app/settings/personalApiToken>.
|
|
28
|
+
Create the key, copy it, come back to the terminal and press Enter. The setup reads the key from your
|
|
29
|
+
clipboard (or paste it, hidden), checks it with Garmin, stores it in your system keychain and configures
|
|
30
|
+
your MCP clients.
|
|
31
|
+
3. **Restart your MCP client** and ask: *"How many km did I run last week?"*
|
|
32
|
+
|
|
33
|
+
That's all. To check that everything works at any time: `uvx garmin-dynamic-mcp doctor`.
|
|
34
|
+
|
|
35
|
+
## What you can ask
|
|
36
|
+
|
|
37
|
+
Claude composes the requests itself and does the maths and the charts, so you are not limited to preset questions:
|
|
38
|
+
|
|
39
|
+
- "How many km did I run last week?"
|
|
40
|
+
- "What is my average cadence over my last ten runs?"
|
|
41
|
+
- "Chart the km I ran each day last month."
|
|
42
|
+
- "How did my sleep and HRV change over the last 90 days?"
|
|
43
|
+
- "Which weeks had the highest training load this year?"
|
|
44
|
+
|
|
45
|
+
## Supported clients
|
|
46
|
+
|
|
47
|
+
`setup` finds the clients installed on your machine and configures them. For anything else it prints the snippet to paste.
|
|
48
|
+
|
|
49
|
+
| Client | Configured by `setup` |
|
|
50
|
+
|---|---|
|
|
51
|
+
| Claude Desktop | yes (config file) |
|
|
52
|
+
| Claude Code | yes (`claude mcp add`, user scope) |
|
|
53
|
+
| Cursor | yes (`~/.cursor/mcp.json`) |
|
|
54
|
+
| VS Code | yes (user `mcp.json`) |
|
|
55
|
+
| Windsurf / Devin Desktop | yes, when its config file exists |
|
|
56
|
+
| Gemini CLI | yes, when `~/.gemini/settings.json` exists |
|
|
57
|
+
| Codex CLI | yes (`codex mcp add`) |
|
|
58
|
+
| Anything else (Zed, ...) | prints the snippet, see [Manual configuration](#manual-configuration) |
|
|
59
|
+
|
|
60
|
+
`setup` never touches a configuration file it cannot parse as plain JSON (for example one with comments): it prints
|
|
61
|
+
the snippet instead. Before its first change to a file it saves a backup next to it.
|
|
62
|
+
|
|
63
|
+
## How it stays up to date
|
|
64
|
+
|
|
65
|
+
Garmin's Personal API is new and still growing. This server does not hard-code its endpoints:
|
|
66
|
+
|
|
67
|
+
1. Every day a GitHub Action downloads Garmin's published OpenAPI specification and compares it with the one the
|
|
68
|
+
catalog was built from.
|
|
69
|
+
2. If something changed (new endpoint, new parameter, different limit), the Action regenerates the endpoint catalog
|
|
70
|
+
and opens a pull request that lists exactly what changed.
|
|
71
|
+
3. A maintainer reviews and merges it. A release is published automatically.
|
|
72
|
+
4. Your server tells you, inside the conversation, that a new version exists. You choose when to update:
|
|
73
|
+
`uvx garmin-dynamic-mcp@latest update`, then restart your client.
|
|
74
|
+
|
|
75
|
+
The server never downloads a catalog by itself while running: what it can call is always something a human reviewed.
|
|
76
|
+
If Garmin changes the page the Action reads, it opens an issue instead of failing silently.
|
|
77
|
+
|
|
78
|
+
## Security
|
|
79
|
+
|
|
80
|
+
- **Your key stays in the OS keychain** (Windows Credential Manager, macOS Keychain, Linux Secret Service), not in a
|
|
81
|
+
JSON file. `setup` never writes it into a client configuration.
|
|
82
|
+
- **Read-only and locked down.** Only `GET` requests, only to Garmin's API host, only to paths in the catalog, with
|
|
83
|
+
validated parameters. Nothing accepts a free-form URL.
|
|
84
|
+
- **Sensitive data is off by default** (nutrition, menstrual cycle): see [Sensitive endpoints](#sensitive-endpoints).
|
|
85
|
+
- **No surprise updates.** Client configurations pin an exact version. The server only tells you when a newer one exists.
|
|
86
|
+
- **Supply chain.** Releases are built by CI and published to PyPI with trusted publishing (no stored token) and
|
|
87
|
+
attestations; GitHub Actions are pinned by commit.
|
|
88
|
+
|
|
89
|
+
Details and the threat model: [docs/security.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/security.md). To report a vulnerability: [SECURITY.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/SECURITY.md).
|
|
90
|
+
|
|
91
|
+
## Privacy
|
|
92
|
+
|
|
93
|
+
- The server runs on your computer. The key is sent only to Garmin.
|
|
94
|
+
- The only other connection it makes is a daily check of PyPI for a newer version (no data about you is sent).
|
|
95
|
+
Disable it with `GARMIN_MCP_NO_UPDATE_CHECK=1`.
|
|
96
|
+
- What you ask Claude for becomes part of your conversation, like any tool result. Consider which questions you ask.
|
|
97
|
+
- Garmin's Personal API is for accessing **your own data** with **your own key**. Garmin does not intend it for commercial
|
|
98
|
+
applications serving several users. Read [Garmin's terms](https://developer.garmin.com/gc-developer-program/personal/personal-faq/).
|
|
99
|
+
|
|
100
|
+
## Updating
|
|
101
|
+
|
|
102
|
+
When a newer version exists, the answers of the tools include an `update_available` note and Claude will tell you. To update:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
uvx garmin-dynamic-mcp@latest update
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
then restart your MCP client. Prefer not to be told? Set `GARMIN_MCP_NO_UPDATE_CHECK=1` in the server's environment.
|
|
109
|
+
|
|
110
|
+
## Troubleshooting
|
|
111
|
+
|
|
112
|
+
Run `uvx garmin-dynamic-mcp doctor` first: it checks the key, the connection to Garmin, your version and every client
|
|
113
|
+
configuration, and never prints the key.
|
|
114
|
+
|
|
115
|
+
- **"expired or was revoked"**: create a new key on Garmin and run `uvx garmin-dynamic-mcp setup` again; it replaces the old one.
|
|
116
|
+
Garmin emails you about a week before a key expires.
|
|
117
|
+
- **Claude Desktop does not start the server**: it may not see `uvx` on its PATH. `setup` writes the absolute path of
|
|
118
|
+
`uvx`; if you moved it, run `setup` again. Quit Claude Desktop completely (also from the tray or the menu bar) and reopen it.
|
|
119
|
+
- **No system keychain** (some Linux servers): `setup --allow-file-storage` stores the key in an owner-only file instead.
|
|
120
|
+
- **A long period returns fewer rows than expected**: responses are capped (below); Claude is told how to narrow the request.
|
|
121
|
+
|
|
122
|
+
## Manual configuration
|
|
123
|
+
|
|
124
|
+
If you prefer to edit the configuration yourself, add this to your client's MCP servers (the key is read from the
|
|
125
|
+
keychain, so run `setup` once with `--clients none` first):
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"mcpServers": {
|
|
130
|
+
"garmin": {
|
|
131
|
+
"command": "uvx",
|
|
132
|
+
"args": ["garmin-dynamic-mcp==0.2.0"]
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
VS Code uses the top-level key `servers` and needs `"type": "stdio"`. For Claude Code:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
claude mcp add garmin --scope user -- uvx garmin-dynamic-mcp==0.2.0
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
If you do not want to use the keychain at all, set `GARMIN_API_KEY` in the server's `env` instead. That puts the key in
|
|
145
|
+
a plain-text file, which is why `setup` does not do it.
|
|
146
|
+
|
|
147
|
+
## What it reads, and its limits
|
|
148
|
+
|
|
149
|
+
Two generic tools: `list_endpoints` (what exists, with parameters; optional `query`) and `get` (call one endpoint).
|
|
150
|
+
|
|
151
|
+
- Activities (list, details, workouts), daily summaries, steps, sleep, HRV, stress, Body Battery, heart rate, SpO2, weight,
|
|
152
|
+
hydration, heart-rate zones, fitness age, profile settings. The exact list is in
|
|
153
|
+
[`catalog.json`](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/src/garmin_dynamic_mcp/catalog.json); [docs/garmin-api-findings.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/garmin-api-findings.md) says
|
|
154
|
+
which endpoints were verified against a real account.
|
|
155
|
+
- The server renews the 24-hour token, fetches activity pages (200 per request, up to 1000 activities per answer, at most
|
|
156
|
+
20 requests), splits long date ranges where Garmin enforces a limit, lets Claude pick fields, and truncates answers at about
|
|
157
|
+
40,000 characters with a note on how to narrow the request.
|
|
158
|
+
- It does not download `.FIT` files (second-by-second data) yet, and never writes anything to Garmin or your watch.
|
|
159
|
+
|
|
160
|
+
## Sensitive endpoints
|
|
161
|
+
|
|
162
|
+
Nutrition and menstrual-cycle endpoints are in the catalog but **disabled**. To enable them set
|
|
163
|
+
`GARMIN_MCP_ENABLE_SENSITIVE=1` in the server's environment. They have not been verified against a real account.
|
|
164
|
+
|
|
165
|
+
## Development
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
uv sync
|
|
169
|
+
uv run pytest # mocked HTTP, no key needed
|
|
170
|
+
uv run ruff check . && uv run ruff format --check . && uv run mypy
|
|
171
|
+
uv run python scripts/fetch_openapi.py build/openapi.json
|
|
172
|
+
uv run python scripts/build_catalog.py build/openapi.json
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
See [CONTRIBUTING.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/CONTRIBUTING.md). Releases: [docs/releasing.md](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/docs/releasing.md).
|
|
176
|
+
|
|
177
|
+
## Disclaimer
|
|
178
|
+
|
|
179
|
+
This is an independent open-source project. It is **not affiliated with, endorsed by or supported by Garmin Ltd.**
|
|
180
|
+
"Garmin" and "Garmin Connect" are trademarks of Garmin Ltd. Use of the Personal API is subject to Garmin's terms.
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
[MIT](https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/LICENSE)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "garmin-dynamic-mcp"
|
|
3
|
+
version = "0.2.0"
|
|
4
|
+
description = "Dynamic, secure, read-only MCP server for the Garmin Connect Personal API"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
authors = [{ name = "Fabrizio De Bortoli" }]
|
|
10
|
+
keywords = ["mcp", "model-context-protocol", "garmin", "garmin-connect", "claude", "fitness", "health"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: End Users/Desktop",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.10",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Information Analysis",
|
|
21
|
+
"Typing :: Typed",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"mcp>=2,<3",
|
|
25
|
+
"httpx>=0.27",
|
|
26
|
+
"keyring>=25",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/fabriziodebortoli/garmin-dynamic-mcp"
|
|
31
|
+
Repository = "https://github.com/fabriziodebortoli/garmin-dynamic-mcp"
|
|
32
|
+
Issues = "https://github.com/fabriziodebortoli/garmin-dynamic-mcp/issues"
|
|
33
|
+
Changelog = "https://github.com/fabriziodebortoli/garmin-dynamic-mcp/blob/main/CHANGELOG.md"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
garmin-dynamic-mcp = "garmin_dynamic_mcp.cli:entry_point"
|
|
37
|
+
|
|
38
|
+
[dependency-groups]
|
|
39
|
+
dev = [
|
|
40
|
+
"pytest>=8",
|
|
41
|
+
"pytest-asyncio>=0.23",
|
|
42
|
+
"pytest-cov>=5",
|
|
43
|
+
"respx>=0.21",
|
|
44
|
+
"ruff>=0.6",
|
|
45
|
+
"mypy>=1.11",
|
|
46
|
+
]
|
|
47
|
+
|
|
48
|
+
[build-system]
|
|
49
|
+
requires = ["hatchling>=1.26"]
|
|
50
|
+
build-backend = "hatchling.build"
|
|
51
|
+
|
|
52
|
+
[tool.hatch.build.targets.wheel]
|
|
53
|
+
packages = ["src/garmin_dynamic_mcp"]
|
|
54
|
+
|
|
55
|
+
[tool.hatch.build.targets.sdist]
|
|
56
|
+
include = ["/src", "/README.md", "/LICENSE", "/CHANGELOG.md", "/pyproject.toml"]
|
|
57
|
+
|
|
58
|
+
[tool.pytest.ini_options]
|
|
59
|
+
asyncio_mode = "auto"
|
|
60
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
61
|
+
testpaths = ["tests"]
|
|
62
|
+
markers = ["live: needs GARMIN_API_KEY and network (skipped otherwise)"]
|
|
63
|
+
|
|
64
|
+
[tool.ruff]
|
|
65
|
+
line-length = 120
|
|
66
|
+
target-version = "py310"
|
|
67
|
+
|
|
68
|
+
[tool.ruff.lint]
|
|
69
|
+
select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
|
|
70
|
+
ignore = ["RUF001", "RUF002", "RUF003"]
|
|
71
|
+
|
|
72
|
+
[tool.ruff.lint.per-file-ignores]
|
|
73
|
+
"tests/**" = ["S101", "S105", "S106"]
|
|
74
|
+
"scripts/**" = ["S603"]
|
|
75
|
+
|
|
76
|
+
[tool.mypy]
|
|
77
|
+
python_version = "3.10"
|
|
78
|
+
strict = true
|
|
79
|
+
files = ["src"]
|
|
File without changes
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"""Garmin personal API key -> access token (24 hours, no refresh token)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import base64
|
|
6
|
+
import json
|
|
7
|
+
import time
|
|
8
|
+
from collections.abc import Callable
|
|
9
|
+
|
|
10
|
+
import httpx
|
|
11
|
+
|
|
12
|
+
from .errors import GarminError
|
|
13
|
+
|
|
14
|
+
TOKEN_URL = "https://personal.connectapi.garmin.com/personalapitoken-service/personal-api/personal-api-key/token" # noqa: S105 (a URL, not a secret)
|
|
15
|
+
KEY_PAGE = "https://connect.garmin.com/app/settings/personalApiToken"
|
|
16
|
+
SETUP_HINT = "run: uvx garmin-dynamic-mcp setup"
|
|
17
|
+
_REFRESH_MARGIN_S = 60
|
|
18
|
+
_FULL_LIFETIME_S = 24 * 3600
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def normalize_key(raw: str | None) -> str:
|
|
22
|
+
"""Strip spaces, line breaks and quotes pasted by mistake."""
|
|
23
|
+
key = (raw or "").replace("", "").strip().strip("\"'").strip()
|
|
24
|
+
if not key:
|
|
25
|
+
raise GarminError(
|
|
26
|
+
"key_missing",
|
|
27
|
+
f"No Garmin key found. Create one at {KEY_PAGE} and {SETUP_HINT}",
|
|
28
|
+
)
|
|
29
|
+
if not key.isascii() or any(ch.isspace() for ch in key):
|
|
30
|
+
raise GarminError(
|
|
31
|
+
"key_missing",
|
|
32
|
+
f"The Garmin key contains spaces or unexpected characters: copy it again from {KEY_PAGE} and {SETUP_HINT}",
|
|
33
|
+
)
|
|
34
|
+
return key
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _jwt_times(token: str) -> tuple[float, float]:
|
|
38
|
+
try:
|
|
39
|
+
payload = token.split(".")[1]
|
|
40
|
+
payload += "=" * (-len(payload) % 4)
|
|
41
|
+
claims = json.loads(base64.urlsafe_b64decode(payload))
|
|
42
|
+
return float(claims["iat"]), float(claims["exp"])
|
|
43
|
+
except (IndexError, KeyError, ValueError, TypeError) as err:
|
|
44
|
+
raise GarminError("upstream", "Garmin returned an invalid token. Try again later.") from err
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def token_lifetime(token: str) -> float:
|
|
48
|
+
"""Seconds between the token's issue and expiry (24 h, or less when the key expires sooner)."""
|
|
49
|
+
iat, exp = _jwt_times(token)
|
|
50
|
+
return exp - iat
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class TokenManager:
|
|
54
|
+
def __init__(
|
|
55
|
+
self,
|
|
56
|
+
api_key: str,
|
|
57
|
+
http: httpx.AsyncClient,
|
|
58
|
+
clock: Callable[[], float] = time.time,
|
|
59
|
+
) -> None:
|
|
60
|
+
self._api_key = api_key
|
|
61
|
+
self._http = http
|
|
62
|
+
self._clock = clock
|
|
63
|
+
self._token: str | None = None
|
|
64
|
+
self._exp = 0.0
|
|
65
|
+
self.key_expiry_warning: str | None = None
|
|
66
|
+
|
|
67
|
+
def invalidate(self) -> None:
|
|
68
|
+
self._token = None
|
|
69
|
+
|
|
70
|
+
async def token(self) -> str:
|
|
71
|
+
if self._token is not None and self._clock() < self._exp - _REFRESH_MARGIN_S:
|
|
72
|
+
return self._token
|
|
73
|
+
token = await self._exchange()
|
|
74
|
+
iat, exp = _jwt_times(token)
|
|
75
|
+
lifetime = exp - iat
|
|
76
|
+
# Expiry measured on the local clock from the token's own lifetime, so a skewed clock
|
|
77
|
+
# neither re-exchanges on every call nor keeps an expired token.
|
|
78
|
+
self._token, self._exp = token, self._clock() + lifetime
|
|
79
|
+
if lifetime < _FULL_LIFETIME_S:
|
|
80
|
+
hours = max(0, int(lifetime // 3600))
|
|
81
|
+
self.key_expiry_warning = (
|
|
82
|
+
f"Your Garmin key expires in about {hours} hours: create a new one at {KEY_PAGE} and {SETUP_HINT}"
|
|
83
|
+
)
|
|
84
|
+
else:
|
|
85
|
+
self.key_expiry_warning = None
|
|
86
|
+
return token
|
|
87
|
+
|
|
88
|
+
async def _exchange(self) -> str:
|
|
89
|
+
try:
|
|
90
|
+
response = await self._http.post(TOKEN_URL, headers={"Authorization": f"ApiKey {self._api_key}"})
|
|
91
|
+
except httpx.TransportError as err:
|
|
92
|
+
raise GarminError("network", "Cannot reach Garmin: check your connection and try again.") from err
|
|
93
|
+
status = response.status_code
|
|
94
|
+
if status in (400, 401, 403):
|
|
95
|
+
raise GarminError(
|
|
96
|
+
"key_rejected",
|
|
97
|
+
f"Your Garmin key has expired or was revoked (or is not valid). Create a new key at {KEY_PAGE} "
|
|
98
|
+
f"and {SETUP_HINT}",
|
|
99
|
+
)
|
|
100
|
+
if status == 429:
|
|
101
|
+
raise GarminError("rate_limited", "Garmin is rate-limiting requests: try again in a few minutes.")
|
|
102
|
+
if status >= 400:
|
|
103
|
+
raise GarminError("upstream", f"Garmin answered with an error (HTTP {status}). Try again later.")
|
|
104
|
+
token = response.text.strip()
|
|
105
|
+
if not token:
|
|
106
|
+
raise GarminError("upstream", "Garmin answered without a token. Try again later.")
|
|
107
|
+
return token
|