garmin-mcp
# garmin-mcp
> [!WARNING]
> This project is entirely vibe-coded. This line is the only line written by a human in the entire codebase.
A local [MCP](https://modelcontextprotocol.io) server that gives AI assistants **read-only** access to
your [Garmin Connect](https://connect.garmin.com) health and activity data. It is built on the
community [`garminconnect`](https://github.com/cyberjunky/python-garminconnect) library, so it uses your
normal Garmin account login. There is no official Garmin API key involved.
Everything runs on your machine. Your credentials are only used by `garmin-mcp login`; only session
tokens are stored (`~/.garmin-mcp/garmin_tokens.json`, mode `0600`).
## What you can ask
Activities (runs, rides, swims, strength, ... with splits, laps, HR/power zones, weather, gear, GPS file
export), sleep, heart rate, resting HR, HRV, stress, Body Battery, SpO2, respiration, steps, floors,
intensity minutes, hydration, weight and body composition, blood pressure, training readiness/status,
VO2 max, race predictions, endurance and hill score, lactate threshold, FTP, devices, goals, badges,
and more (about 260 read methods in total).
## Install
Requires macOS/Linux with [uv](https://docs.astral.sh/uv/) (`brew install uv`).
```sh
git clone <this repo> garmin-mcp && cd garmin-mcp
uv sync
uv run garmin-mcp login # email, password, MFA code if enabled
uv run garmin-mcp status # verify
```
## Connect it to a client
### Claude Desktop (stdio)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"garmin": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/garmin-mcp", "garmin-mcp", "serve"]
}
}
}
```
### OpenCode
Add to `~/.config/opencode/opencode.json`
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"garmin-mcp": {
"type": "local",
"command": ["uv", "run", "garmin-mcp", "serve"],
"enabled": true,
"environment": {
"UV_WORKING_DIR": "/absolute/path/to/garmin-mcp"
}
}
}
}
```
### Claude Code / others
```sh
claude mcp add garmin -- uv run --directory /absolute/path/to/garmin-mcp garmin-mcp serve
```
### Local HTTP server
```sh
uv run garmin-mcp serve --transport http --port 8765 # http://127.0.0.1:8765/mcp
```
The HTTP endpoint has **no authentication** and binds to `127.0.0.1` by default. Anything on your machine
can read your Garmin data through it. Don't expose it to a network.
## Tools
Two toolsets (`serve --toolset core|all`):
| Toolset | What you get |
| --- | --- |
| `core` (default) | About 60 curated tools for the common data, plus `garmin_list_methods` and `garmin_call` to discover and run **any** other read method. Keeps the tool list small for clients that struggle with hundreds of tools. |
| `all` | Every read method registered as its own tool (about 260). |
Always available: `get_today` (today's date in your Garmin timezone), `garmin_api_get` (raw GET against any
Garmin Connect API path), and `download_activity` (saves a TCX/GPX/KML/CSV or original FIT zip to
`~/.garmin-mcp/downloads` and returns the path).
Only read methods are exposed. Nothing can create, edit or delete data on your Garmin account.
Large responses (e.g. a full day of per-minute heart rate, or an activity's chart data) are automatically
downsampled to fit `--max-chars` (default 100000), and the result says so; ask for a shorter range to get full
resolution.
## Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| `GARMIN_MCP_TOKENSTORE` | `~/.garmin-mcp` | Where session tokens live |
| `GARMIN_MCP_DOWNLOAD_DIR` | `<tokenstore>/downloads` | Where `download_activity` writes |
| `GARMIN_IS_CN` | unset | Set to `true` for Garmin China accounts |
| `GARMIN_EMAIL`, `GARMIN_PASSWORD` | unset | Optional: used by `login` instead of prompting, and by the server as a fallback if no tokens exist (accounts without MFA only) |
Tokens refresh automatically. If Garmin rejects them, tools return an error asking you to run
`garmin-mcp login` again. `garmin-mcp logout` deletes the saved tokens.
## Development
```sh
uv run pytest
uv run ruff check . && uv run ruff format .
```
Tests use a fake Garmin client and exercise the real MCP protocol (in-memory and over stdio); they need no
account.
## Notes
- This relies on unofficial endpoints and may break if Garmin changes them. Logging in too often can get you
rate limited, which is why tokens are reused.
- Not affiliated with Garmin.
TDQS
Scored across 62 tools
Many tools overlap heavily: get_daily_heart_rate_stats vs get_heart_rates vs get_rhr_day; get_daily_stress_stats vs get_stress_data; get_steps_data vs get_daily_steps; and several activity-detail variants (get_activity, get_activity_details, get_activity_splits, get_activity_typed_splits, get_activity_split_summaries). Descriptions help in places, but an agent can easily choose the wrong endpoint for the same underlying data.
Most tools follow a get_<noun> snake_case pattern, but there are noticeable deviations: garmin_api_get, garmin_list_methods, garmin_call, download_activity, and get_today break the dominant convention. Minor inconsistencies like get_fitnessage_data and get_weigh_ins also reduce predictability.
62 tools is excessive for a read-only data server, especially because many endpoints are near-duplicates and generic escape hatches (garmin_api_get, garmin_call, garmin_list_methods) already cover undocumented data. Consolidation would make the surface far easier to navigate.
For a read-only Garmin Connect surface, coverage is broad: daily metrics, activities, sleep, body composition, training status, devices, goals, badges, raw API access, and downloads are all present. Some niche domains rely on the generic fallback rather than dedicated tools, but there are few obvious hard dead ends.