Skip to main content
Glama
garmin-everything-mcp

garmin-everything-mcp

by dlekdns08
README.md
<h1 align="center">garmin-everything-mcp</h1>

<p align="center"><strong>The other 70% of your Garmin.</strong></p>

<p align="center">
An MCP server that exposes <em>everything</em> in Garmin Connect that
<a href="https://github.com/Taxuspt/garmin_mcp">garmin_mcp</a> does not.
Run it <strong>side by side</strong> with garmin_mcp: it adds hundreds of tools without duplicating a single name.
</p>

<p align="center">
<code>garminconnect 0.3.20: 348 methods | garmin_mcp covers 109 | garmin-everything-mcp adds 178 (extras) / 265 (all) / 338 (full) auto-generated tools + 8 hand-written</code>
</p>

---

[garmin_mcp](https://github.com/Taxuspt/garmin_mcp) is excellent, but it hand-wraps **105** calls of the
[python-garminconnect](https://github.com/cyberjunky/python-garminconnect) library, pinned at 0.3.2.
The library is now at **0.3.20 with 348 public methods**: sleep need and skin temperature, HRV baselines,
training load balance, ECG, glucose, health snapshots, jet lag, race predictions, power curves, one-rep max,
gear, courses, calendars, reports, golf, menstrual health, and dozens of daily/weekly/monthly *range* endpoints.

This server does not hand-wrap anything. It **introspects `garminconnect.Garmin` at startup** and turns every
public method into an MCP tool: name, typed parameters, defaults and docstring come straight from the library.
When python-garminconnect gains a method, this server gains a tool. A shipped list of what garmin_mcp already
provides keeps the two servers disjoint, and eight hand-written tools do what reflection cannot: compact ranges,
downsampled time series, a raw endpoint escape hatch, and an offline export.

## Highlights

- **Reflection-generated tools**: 178 read-only tools in the default `extras` profile, 265 in `all`, 338 with writes.
  See [docs/COVERAGE.md](docs/COVERAGE.md) for the full 348-row matrix.
- **Zero duplicates with garmin_mcp**: the `extras` profile excludes every method and tool name garmin_mcp registers.
- **8 hand-written power tools**: `garmin_daily_range`, `garmin_activity_timeseries`, `garmin_sleep_detail`,
  `garmin_intraday`, `garmin_raw_get`, `garmin_endpoint_catalog`, `garmin_export`, `garmin_coverage`.
- **Context-safe by default**: a 60 KB size budget summarises huge payloads instead of flooding the model;
  a 1 MB activity detail becomes a 4 KB columnar series.
- **Privacy by default**: email, names, birth date, address and phone fields are redacted recursively.
- **Write-safe by default**: every `add_/create_/delete_/update_/set_/upload_/...` method stays hidden unless you
  opt in twice (`profile=full` **and** `GARMIN_EVERYTHING_WRITES=1`). Tools carry MCP `readOnlyHint` annotations.
- **Same auth as garmin_mcp**: authenticate once with `garmin-mcp-auth`; both servers read `~/.garminconnect`.

## Quick start

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
# 1. Authenticate once (this is garmin_mcp's auth tool; tokens land in ~/.garminconnect)
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth

# 2. Run the server (stdio)
uvx --python 3.12 --from git+https://github.com/dlekdns08/garmin-everything-mcp garmin-everything-mcp
```

The server never prompts for credentials and never stores anything but what the library already keeps.

## The composition recipe: run both servers

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`) or any MCP client:

```json
{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"]
    },
    "garmin-everything": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "git+https://github.com/dlekdns08/garmin-everything-mcp", "garmin-everything-mcp"],
      "env": {
        "GARMIN_EVERYTHING_PROFILE": "extras"
      }
    }
  }
}
```

Claude Code:

```bash
claude mcp add garmin -- uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp
claude mcp add garmin-everything -e GARMIN_EVERYTHING_PROFILE=extras -- \
  uvx --python 3.12 --from git+https://github.com/dlekdns08/garmin-everything-mcp garmin-everything-mcp
```

`extras` is the default, so the `env` block is optional. With it, no tool name exists in both servers.
Prefer a single server? Use `GARMIN_EVERYTHING_PROFILE=all` and drop garmin_mcp (you lose its workout builders
and FIT parsing, which are not library methods).

## The hand-written tools

| Tool | What it does |
|---|---|
| `garmin_daily_range(metric, start, end)` | One compact row per day for `sleep_score, sleep, body_battery, resting_hr, stress, steps, steps_monthly, floors, hydration, respiration, intensity_minutes, hrv, calories_weekly, vo2max_weekly, weight`. Uses the verified range endpoints, chunked in 28-day windows: 60 days of resting HR is 3 calls and 5 KB, not 60 calls. |
| `garmin_activity_timeseries(activity_id, metrics, points)` | Maps `metricDescriptors` to columns and downsamples `activityDetailMetrics` to N points (uniform stride, timestamps kept). 1,188 samples / 990 KB becomes 50 points / 3.7 KB. `metrics="all"` for every descriptor. |
| `garmin_sleep_detail(date, include, points)` | The sleep sub-objects garmin_mcp drops: sleep need and next-night need, naps, skin-temperature deviation, breathing disruptions, HRV series + status, movement, restless moments, body battery, heart rate, stress, respiration. |
| `garmin_intraday(date, kind, points)` | Downsampled intraday series: `heart_rate` (2-min bpm), `steps_epochs` (15-min), `movement` (1-min), `respiration`, `stress`, `body_battery`, `spo2`. Scalars come back as `summary`. |
| `garmin_raw_get(path, params, fields, jq_path)` | GET any Connect API path. `{dn}` becomes your display name. `fields` keeps top-level keys, `jq_path` picks a sub-tree (`a.b[0].c`, `items[*].value`, `items[0:5]`), no jq binary needed. |
| `garmin_endpoint_catalog(search)` | 54 paths verified against a real account plus ~270 path templates extracted from the library source by `scripts/gen_endpoints.py`, with notes on which were verified and which returned 404 for the probing account. |
| `garmin_export(start, end, out_dir, metrics)` | Writes one JSONL file per metric (one line per day) to `~/.cache/garmin-everything-mcp/export` with 0.3 s pacing. Read-only against Garmin; redaction applies. Returns a manifest. |
| `garmin_coverage()` | Live matrix: library version, profile, tools per group, what garmin_mcp covers, what was excluded and why. |

Examples (as the model would call them):

```text
garmin_daily_range(metric="sleep_score", start="2026-11-11", end="2026-11-17")
-> {"metric":"sleep_score","calls":1,"rows":7,"data":[{"date":"2026-11-11","value":65}, ...]}

garmin_activity_timeseries(activity_id="12345678901", metrics="directHeartRate,directPower", points=100)
-> {"totalPoints":1188,"returnedPoints":100,"columns":["directTimestamp","sumDuration","directHeartRate","directPower"],
    "units":{"directHeartRate":"bpm","directPower":"watt"},"series":{"directHeartRate":[127,135,...],...}}

garmin_sleep_detail(date="2026-11-16", include="hrv,skin_temp,breathing")
-> {"summary":{"sleepTimeSeconds":24462,"sleepNeed":{"actual":500,"feedback":"INCREASED",...},"sleepScores":{...}},
    "hrv":{"hrvData":{"count":86,"returned":120,"values":[[1794746901000,32.0],...]},"avgOvernightHrv":48.0,"hrvStatus":"UNBALANCED"},
    "skin_temp":{"avgSkinTempDeviationC":0.3},"breathing":{"breathingDisruptionData":{...}}}

garmin_raw_get(path="/wellness-service/stats/daily/sleep/score/2026-11-11/2026-11-17", jq_path="[*].value")
-> [65,54,48,69,86,73,76]
```

Everything else is auto-generated. A few of the 178 extras: `get_sleep_daily`, `get_sleep_stats_weekly`,
`get_hrv_data_range`, `get_daily_body_battery_stats`, `get_training_four_week_load_balance`,
`get_training_readiness_range`, `get_heart_rate_zones_v2`, `get_power_zones`, `get_sensors`, `get_ecg_list`,
`get_glucose_data`, `get_health_snapshots`, `get_jetlag_status`, `get_personal_record_candidates`,
`get_fastest_splits`, `get_activity_laps`, `get_activity_power_curve`, `get_gear_list`, `get_calendar_week`,
`get_upcoming_events`, `get_golf_summary`, `get_menstrual_cycle_summary`, `search_activities`, ...

## Profiles and environment

| Variable | Default | Effect |
|---|---|---|
| `GARMIN_EVERYTHING_PROFILE` | `extras` | `extras`: read methods garmin_mcp lacks. `all`: every read method. `full`: read + write. CLI: `--profile`. |
| `GARMIN_EVERYTHING_WRITES` | unset | Must be `1` for `full` to actually register write tools. |
| `GARMIN_EVERYTHING_GROUPS` | all | Comma list of groups to keep: `sleep,hrv,stress,body_battery,heart_rate,steps,floors,respiration,spo2,hydration,weight,nutrition,blood_pressure,glucose,ecg,health_snapshot,training,metrics,activities,workouts,courses,gear,devices,badges,challenges,calendar,goals,jetlag,menstrual,golf,profile,reports,other`. |
| `GARMIN_ENABLED_TOOLS` | unset | Comma allowlist of auto-generated tool names (case-insensitive), same semantics as garmin_mcp. |
| `GARMIN_DISABLED_TOOLS` | unset | Comma denylist; ignored when the allowlist is set. |
| `GARMIN_EVERYTHING_MAX_BYTES` | `60000` | Size budget per result; larger payloads are summarised. `0` disables. |
| `GARMIN_EVERYTHING_REDACT` | `1` | Recursive redaction of personal keys. Set `0` to disable. |
| `GARMIN_EVERYTHING_CALL_TIMEOUT` | `90` | Seconds before a stalled Garmin request is abandoned. `0` disables. |
| `GARMIN_EVERYTHING_EXPORT_DIR` | `~/.cache/garmin-everything-mcp/export` | Default directory for `garmin_export`. |
| `GARMIN_EVERYTHING_DOWNLOAD_DIR` | `~/.cache/garmin-everything-mcp/downloads` | Where the `download_*` tools save files. |
| `GARMIN_EVERYTHING_TRANSPORT` / `HOST` / `PORT` | `stdio` / `127.0.0.1` / `8001` | Also `--transport streamable-http --port 8001` on the CLI. |
| `GARMINTOKENS` | `~/.garminconnect` | Token directory, identical to garmin_mcp. |
| `GARMINTOKENS_BASE64` | `~/.garminconnect_base64` | Base64 token file fallback, identical to garmin_mcp. |
| `GARMIN_IS_CN` | `false` | Use garmin.cn. |

The hand-written `garmin_*` tools are always registered.

## Size budget and redaction

Every tool returns a JSON string. If it exceeds `GARMIN_EVERYTHING_MAX_BYTES`, you get a structural summary
(keys, list lengths, first items) with `"truncated": true`, the original size, and a hint pointing at
`garmin_raw_get(fields=, jq_path=)` or the downsampling tools. Errors come back as
`{"error": ..., "type": ..., "hint": ...}` with actionable hints (expired tokens, rate limit, 404 for a feature your
device lacks, bad date format). The server never crashes on a tool call.

Redaction masks, recursively and case-insensitively, any key matching `email`, `userName`, `firstName`,
`lastName`, `fullName`, `displayName`, `birthDate`, `address`, `phone` (including prefixed variants such as
`ownerFullName`) with `"[redacted]"`. The display name is still used internally for URL paths. Numeric ids
(profile, device, activity) are not redacted because tools need them as parameters.

## Raw endpoint escape hatch

`garmin_endpoint_catalog(search="metrics-service")` lists what is known; `garmin_raw_get` calls it. The catalog
bundles two sources: paths **verified** on 2026-11-17 against a real account (shapes noted), and every
`*-service/` path template the installed library touches, extracted by walking its AST
(`scripts/gen_endpoints.py`). Fifteen library methods returned 404/400 for the probing account (naps, lifetime
totals, acclimation, running economy, power curve, one-rep max, ECG, health snapshots, ...) and are flagged; they
may work for you if your device records that data.

## Write safety

Methods are classified by name prefix: `add_ create_ delete_ update_ set_ upload_ schedule_ unschedule_ push_ send_
import_ reschedule_ move_ confirm_ init_ request_ copy_ convert_ remove_` are WRITE, everything else is READ.
Write tools only exist when `GARMIN_EVERYTHING_PROFILE=full` **and** `GARMIN_EVERYTHING_WRITES=1`, are described
with a `[WRITE: modifies your Garmin account]` prefix, and carry `readOnlyHint=false, destructiveHint=true`.
`login`, `logout`, `resume_login`, `request_reload`, the raw `connectapi`/`download` helpers and the GraphQL
escape hatch are never auto-generated. Methods that return bytes (`download_*`) are wrapped by small overrides that
save the file locally and return its path.

## Privacy

This repository contains no personal data: the bundled endpoint lists only hold path templates with `{dn}`
placeholders, tests use a fake Garmin class, and the smoke tests are run locally. Tokens live where garmin_mcp
puts them and are never copied. `garmin_export` writes to your machine only, with redaction applied, and the
`.gitignore` refuses token files and exports by default.

## Updating when python-garminconnect releases

```bash
uv lock --upgrade-package garminconnect
uv run python scripts/gen_endpoints.py     # refresh the endpoint catalog from the new source
uv run python scripts/gen_coverage.py      # refresh docs/COVERAGE.md and the badge line
uv run pytest                              # the committed coverage file is checked against the live registry
```

New methods appear as tools automatically. If one needs special handling (odd signature, bytes return), add it to
`OVERRIDES` or `SKIP` in `src/garmin_everything_mcp/registry.py`.

## Development

```bash
git clone https://github.com/dlekdns08/garmin-everything-mcp && cd garmin-everything-mcp
uv sync
uv run pytest                               # 45 tests, no network
uv run garmin-everything-mcp --profile all  # stdio
npx @modelcontextprotocol/inspector uv run garmin-everything-mcp
```

Layout: `registry.py` (introspection, classification, profiles, overrides), `results.py` (JSON, redaction,
size budget, error hints), `pathsel.py` (jq-like resolver), `client.py` (lazy token login with a lock),
`tools_extra.py` (the eight hand-written tools), `server.py` (FastMCP wiring and CLI),
`data/` (garmin_mcp method and tool name lists, verified and generated endpoint catalogs).

## How the garmin_mcp list was derived

`data/garmin_mcp_wrapped_methods.txt` is the set of `garmin_client.<method>(` calls grepped from garmin_mcp's
`src/garmin_mcp/*.py` (105 names, 99 of which are `Garmin` methods in 0.3.20; the rest are HTTP helpers such as
`post`/`put`). `data/garmin_mcp_tool_names.txt` is every `@app.tool`-decorated function name in the same tree
(153 names), because a few garmin_mcp tools shadow library method names without calling them
(`get_heart_rate_zones`, `get_courses`, `get_calendar_events`, the `get_nutrition_daily_*` trio, ...). The
`extras` profile excludes the union of both lists.

## Credits

- [Taxuspt/garmin_mcp](https://github.com/Taxuspt/garmin_mcp) for the server this one is designed to sit next to,
  and for the token conventions it established.
- [cyberjunky/python-garminconnect](https://github.com/cyberjunky/python-garminconnect) for the library that does
  all the real work. Every tool here is one of its methods.

MIT licensed. Not affiliated with Garmin.