garmin-mcp

A Model Context Protocol (MCP) server for Garmin Connect. Ask Claude (or any MCP client) about your sleep, HRV, Body Battery, stress, training readiness, VO2max, runs and rides, and have it build structured workouts that sync to your watch.

"How did I sleep last night, and am I ready for intervals today?" "Show the splits and heart-rate zones of my last run." "Plot my HRV and resting heart rate for September." "Build me 6 x 400 m at 3:50-4:05/km for Thursday." "Where did I lose time on the climbs in Sunday's ride?"

It works with any Garmin device that syncs to Garmin Connect (Forerunner, Fenix, Epix, Venu, Vivoactive, Edge, Index scales...). It runs locally on your computer, and your password never reaches the server.

Why this one

• Everything, in 39 tools. It covers every one of the 153 tools in Taxuspt/garmin_mcp, mapped one by one in PARITY.md and enforced by a test. Related endpoints sit behind one tool with a metric or kind selector, so the whole server costs a quarter of the context in every chat.

• A login that survives Garmin's changes. Built on python-garminconnect 0.3.x, which recovered from Garmin's March 2026 login change. You log in once in a terminal (MFA supported). The server only reuses the saved tokens and never retries a password login, because repeated attempts can lock an account for days.

• Answers a model can use. Compact JSON with the unit in every key (distance_km, avg_hr_bpm, pace_min_km), in your account's time zone, with today's partial data marked. Garmin's unit quirks (grams, RPE ×10, Fahrenheit, knots, centimetres...) are converted in one place and were checked against Garmin Connect on a real account.

• Deeper analysis. Decodes the original FIT file with Garmin's official FIT SDK: climbs and VAM, time on each grade, aerobic decoupling, power curve, NP/IF/TSS, R-R HRV, running and cycling dynamics, Di2 gear use.

• Safe writes. Every tool carries MCP annotations, so clients know which ones change your account. Deletes always preview first. GARMIN_MCP_READ_ONLY=1 removes every write.

• Windows-proof. A Cloudflare 403 on Windows 11 (python-garminconnect #444) is retried automatically through curl_cffi.

Related MCP server: garmin-mcp-bridge

Quick start

You need uv.

1. Log in once, in a terminal. It asks for your Garmin email, password and, if Garmin sends one, the verification code. Only the tokens are saved, to ~/.garmin-mcp/.

uvx --from git+https://github.com/wiande00/garmin-mcp garmin-mcp-auth login

2. Add the server to your MCP client.

Claude Code:

claude mcp add --scope user garmin -- uvx --from git+https://github.com/wiande00/garmin-mcp garmin-mcp

Claude Desktop (claude_desktop_config.json; quit Claude Desktop completely before editing, since it rewrites the file while running):

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/wiande00/garmin-mcp", "garmin-mcp"]
    }
  }
}

If Claude Desktop can't find uvx, use its full path (which uvx, or where uvx on Windows). Other MCP clients take the same command and arguments. To pin a release, add @v0.1.0 to the git URL.

3. Ask away. Start with "check my Garmin status".

git clone https://github.com/wiande00/garmin-mcp
cd garmin-mcp
uv sync
uv run garmin-mcp-auth login
claude mcp add --scope user garmin -- uv --directory "$PWD" run --quiet garmin-mcp

On Windows with the Microsoft Store edition of Claude Desktop, scripts\add-to-claude-desktop.cmd registers the server for you: double-click it from File Explorer, quit Claude Desktop from its tray icon, and it adds the entry and reopens Claude.

Tools

Five workout templates are also available as MCP resources (workout://templates/...).

Building workouts

garmin_create_workout takes plain steps and emits Garmin's exact workout JSON:

[
  {"type": "warmup", "duration": "10:00", "hr_zone": 2},
  {"repeat": 6, "steps": [
    {"type": "interval", "distance_km": 0.4, "pace_min_km": ["3:50", "4:05"]},
    {"type": "recovery", "duration": "1:30"}
  ]},
  {"type": "cooldown", "lap_button": true}
]

Each step ends one way (duration, distance_km, reps, lap_button) and has at most one target (hr_zone, hr_bpm, pace_min_km, speed_kmh, power_w, power_zone, cadence). Strength steps name an exercise from Garmin's catalog ("exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 80). Running, cycling, swimming, walking, hiking, strength and more are supported.

Configuration

All optional, as environment variables on the server entry:

garmin-mcp --transport streamable-http --port 8765 serves over HTTP on 127.0.0.1 instead of stdio. That transport has no authentication, so it never listens beyond loopback.

Troubleshooting

How it works

src/garmin_mcp/
  server.py          the MCP server: tool names, parameters, descriptions, annotations
  cli.py             garmin-mcp-auth login | status | logout
  auth.py            tokens, the login and its cooldown, why a login doesn't work
  client.py          one Garmin client per process, error translation, cache
  transport.py       the Windows 403 fallback
  units.py           every Garmin unit quirk
  tools/             what each tool does, testable without MCP
    workout_dsl.py   the workout step language and checks for raw workout JSON
    fit.py           FIT decoding (Garmin FIT SDK) and analysis

• The server logs in lazily on the first call, so the MCP handshake never waits on Garmin.

• Calls run in a worker thread with a timeout, serialised so token refreshes stay safe.

• Range views use Garmin's range endpoints where they exist: a 90-day sleep or HRV trend is a few requests, not 90.

• Failures keep Garmin's status and text, and each kind gets its own message.

• garmin_delete deletes only a request previewed in the last 15 minutes.

Development

uv sync
uv run pytest           # no network: a fake Garmin client and synthetic payloads
uv run ruff check
uv run python scripts/smoke.py   # read-only check of every tool against your real account

Issues and pull requests are welcome. For a bug, include the output of garmin_status (it holds no secrets).

Credits

• python-garminconnect by cyberjunky does the hard part: logging in and talking to Garmin Connect.

• Taxuspt/garmin_mcp defined the feature set, and its issue tracker was the best guide to what goes wrong. Endpoints that python-garminconnect doesn't wrap follow its source.

• Garmin FIT SDK decodes activity files.

Disclaimer

This is an unofficial project, not affiliated with or endorsed by Garmin. It uses the same private API as the Garmin Connect apps, which Garmin can change at any time, and Garmin's terms of use don't cover third-party access. Use it with your own account, at your own risk.

License

MIT