garmin-local-mcp

Local-first Garmin data warehouse with an analysis-grade MCP server. Sync once, analyze forever, even when the API is down.

Why another Garmin MCP?

Every existing Garmin MCP server follows the same design: a thin live wrapper around Garmin's rate-limited, unofficial API. Each question your AI assistant asks becomes one or more live API calls that return huge raw JSON blobs (a single raw sleep response runs around 230 KB). Multi-month questions like "how does my sleep correlate with training load?" are impractical, and when Garmin changes its auth (as it did in March 2026, breaking the whole ecosystem), those servers go completely dark, even for data they already fetched yesterday.

This project inverts the architecture:

• Sync once, analyze forever. Incremental sync into a local warehouse: immutable raw JSON snapshots plus a SQLite database, in a directory you own.
• Server-side analysis, compact responses. Trends, correlations, personal baselines, and anomaly detection are computed locally and returned as small columnar tables in a single tool call. Typical responses are under 2 KB, so nothing floods the model's context.
• Offline resilience. An API breakage pauses new syncs only. Every query over already-synced history keeps working.
• A zero-auth fallback. A standalone decoder for Garmin's undocumented wellness FIT messages (sleep score, HRV, skin temperature, sleep stages, naps) ingests manually exported bundles with no login at all. No other Garmin MCP ships this.
• Curated tools. 12 composable tools, not 110.

Try it without a Garmin account

If you don't own a Garmin, or just want to see what the tools return before handing over credentials, seed a synthetic store:

pip install garmin-local-mcp
garmin-local-mcp --data-dir ~/.garmin-mcp-demo demo
garmin-local-mcp --data-dir ~/.garmin-mcp-demo serve

That generates 180 days across every table, then serves them over MCP. No login, no network, no account.

The data is generated rather than recorded, but it is not random. A latent recovery factor drives HRV up while resting heart rate goes down, training load raises the next day's resting heart rate, a six-day illness window sits in the middle of the range, and a few sleep nights are deliberately missing. So the analysis tools have something real to find:

sync_status reports demo_store: true on these stores, so an assistant can never present generated numbers as real measurements. The generator is deterministic — --seed reproduces a store exactly, and --days changes the range. demo refuses to overwrite a database it did not generate.

Quickstart

Requires Python 3.12+.

pip install garmin-local-mcp

Or run it without installing, via uv:

uvx garmin-local-mcp --help

1. Log in once (MFA supported; tokens persist locally, so future runs never ask for a password):

garmin-local-mcp login

2. Backfill your history. The sync is resumable, safe to interrupt, and throttled to be polite to Garmin's servers. A year of history is roughly 1,800 requests; for long backfills, start it and let it run (overnight works well). If it gets rate limited or interrupted, re-run the same command and it resumes where it left off.

garmin-local-mcp sync --from 2026-01-01

3. Register the MCP server with your client (see Client setup for Claude Desktop, Cursor, and other clients):

claude mcp add --scope user garmin -- garmin-local-mcp serve

4. Ask questions. Examples of what Claude can now answer from your local warehouse in one or two tool calls:

• "How does my sleep score correlate with next-day resting HR?"
• "What were my anomalous HRV days this quarter?"
• "Show weekly training load vs sleep for the last 3 months."

Client setup

The server speaks stdio, so any MCP client works. pip install garmin-local-mcp first (or use the uvx variants below, which need nothing installed beyond uv).

Claude Code

claude mcp add --scope user garmin -- garmin-local-mcp serve

Claude Desktop, one-click: download garmin-local-mcp-x.y.z.mcpb from the latest release, then in Claude Desktop open Settings > Extensions > Advanced settings, click "Install Extension…", and select the file. Requires uv on your PATH; the extension installs and runs the server from PyPI via uvx, so no manual Python setup is needed. If the install dialog warns about a missing Python >=3.12, you can ignore it: uv provisions its own interpreter.

Claude Desktop, manual (Settings, then Developer, then Edit Config; add to claude_desktop_config.json):

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

Any other stdio client / no local install (requires uv):

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-local-mcp", "serve"]
    }
  }
}

Note: login and the initial backfill sync are CLI steps (see Quickstart); the MCP server itself never prompts for credentials.

The 12 tools

Only sync and import_fit write anything, and only inside the data directory. The server never prompts: auth problems come back as structured errors with a hint pointing at the login CLI.

Available metric names include resting_hr, sleep_score, hrv, steps, stress_avg, body_battery_high, skin_temp_dev_c, vo2max, fitness_age, achievable_fitness_age, training_load, endurance_score, hill_score, readiness_score, race_5k_s, and about 35 more; any tool given an unknown name returns the full list.

Performance scores

Garmin's periodic fitness scores land in their own performance table: endurance score, hill score (with its endurance and strength sub-scores), training readiness (score, level, recovery time) and race predictions for 5k, 10k, half and full marathon (all in seconds).

These update on Garmin's own cadence rather than daily, so performance is deliberately excluded from gaps — a day without a new endurance score is normal, not a hole. Race predictions and hill score only move after qualifying running activity, so long stretches of nulls are expected for anyone whose training is mostly hiking, cycling or strength work.

Data layout and ownership

Everything lives in one directory you own (default ~/.garmin-mcp, override with the GARMIN_MCP_DATA_DIR environment variable or --data-dir):

~/.garmin-mcp/
├── config.toml                                  # optional settings
├── tokens/                                      # Garmin Connect session tokens
├── raw/daily/YYYY/YYYY-MM-DD/<endpoint>.json    # immutable raw API snapshots
├── raw/activities/<activity_id>.json            # one snapshot per activity
└── garmin.db                                    # SQLite warehouse