garmin-mcp

Read-only MCP server for Garmin Connect: exposes live data tools plus analyze_* tools that cache activity data locally and compute aggregated statistics. Built on the unofficial garminconnect library — see "Unofficial API — risks & rate limits" below. See Privacy for what's read, cached and stored locally.

Tools

Live data

Analysis (cache + aggregates)

list_activities* returns enriched fields per activity: training effect (aerobic/ anaerobic), training load, intensity minutes, HR time-in-zones, moving/elapsed time, speed, elevation, respiration, body-battery delta, lap count and location.

The analyze_* tools cache raw daily data under ~/.garmin-activity/days/ and write aggregated stats (daily/weekly summaries, morning brief + dated history) to GARMIN_OUTPUT_DIR (defaults to ~/.garmin-mcp/output).

Requirements

• Python >= 3.12 (managed by uv/uvx)
• A Garmin Connect account
• Any OS — no platform-specific credential storage

Unofficial API — risks & rate limits

Not affiliated with, endorsed by, or supported by Garmin Ltd.

Garmin has no official API for individuals. This server talks to Garmin Connect through the reverse-engineered garminconnect library, which drives the same endpoints the website and mobile app use. That has consequences worth understanding before you rely on it:

• It can break without warning. Garmin can change or retire these endpoints at any time; when they do, tools may start returning errors until garminconnect (and then this server) is updated. Pin versions if you need stability, and expect occasional breakage.
• Terms of Service. Automated access to Garmin Connect is not covered by an official individual-developer agreement. Use this only against your own account, for personal use, and review Garmin's Terms of Service — you are responsible for how you use it. Abusive or high-volume use risks account rate-limiting or suspension.
• Built-in pacing. Bulk history sync (analyze_backfill) sleeps ~0.3s between days to stay gentle on Garmin's servers. Individual live-data tools issue only a few requests per call.
• Keep request volume modest. Prefer incremental syncs (analyze_day / analyze_brief) over repeatedly backfilling large ranges. Backfill once for history, then refresh a day at a time. Avoid tight loops or scheduling many concurrent syncs — no official rate limit is published, so err on the side of fewer, spaced-out requests.

Setup

1. One-time interactive login

uvx --from rogo-garmin-mcp rogo-garmin-mcp-login

Prompts for your Garmin email, password and the emailed MFA code. Your credentials are used only to obtain OAuth tokens and are never stored; only the resumable tokens are written to ~/.garmin-mcp/tokens (0700). The headless server resumes from those tokens and refreshes them silently, so it never needs your email or password again. Re-run this login if the tokens eventually expire.

2. Add to Claude Code (~/.claude/settings.json)

Installed from PyPI (recommended):

"mcpServers": {
  "garmin": {
    "type": "stdio",
    "command": "uvx",
    "args": ["rogo-garmin-mcp"]
  }
}

Or from a source checkout: uv sync, then use "command": "uv", "args": ["run", "--project", "/path/to/garmin-mcp", "rogo-garmin-mcp"].

3. Add to Claude Desktop (claude_desktop_config.json)

Edit (or create) the config file — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json:

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

Restart Claude Desktop to pick up the new server.

Client compatibility

This is a standard stdio MCP server launched with uvx rogo-garmin-mcp, so any MCP client that supports the stdio transport should work. Only the Claude Code and Claude Desktop setups are documented and exercised here; the others use the same command and are expected to work but are not separately verified.

What you can ask

Once configured, you talk to your agent in plain language and it picks the right tool. A few prompts that map cleanly onto the tools above:

• "Summarize my last 5 runs." → list_activities / list_activities_by_date
• "Am I recovered enough to train hard today?" → get_training_readiness
• "What's my training status, VO2max and fitness age?" → get_training_status / get_fitness_metrics
• "How did I sleep last night, and what was my HRV?" → get_sleep / get_hrv
• "What are my all-time personal records and predicted race times?" → get_personal_records / get_race_predictions
• "Backfill the last 90 days, then give me my morning brief." → analyze_backfill then analyze_brief

Dates: all date parameters use YYYY-MM-DD. For single-date tools (get_training_readiness, get_sleep, get_hrv, analyze_brief, etc.) it's optional — omit it and it defaults to today. Tools that take a date range or a specific day (list_activities_by_date, get_body_composition, analyze_day) require the date(s) to be passed explicitly.

Example output

Tools return plain JSON. The samples below are trimmed for illustration — real payloads carry more fields (see the tables above). The health-summary tools (get_daily_stats, get_sleep, get_hrv) additionally omit any null fields.

list_activities(limit=2):

[
  {
    "id": 12345678901,
    "name": "Morning Run",
    "type": "running",
    "start": "2026-07-06 19:12:44",
    "duration_min": 41.8,
    "distance_km": 7.35,
    "calories": 512,
    "avg_hr": 152,
    "max_hr": 176,
    "aerobic_te": 3.4,
    "anaerobic_te": 0.6,
    "te_label": "TEMPO",
    "training_load": 118,
    "location": "Riverside"
  },
  {
    "id": 12344556677,
    "name": "Strength Training",
    "type": "strength_training",
    "start": "2026-07-05 08:03:10",
    "duration_min": 24.5,
    "calories": 268,
    "avg_hr": 138,
    "vigorous_intensity_min": 12,
    "training_load": 74
  }
]

get_training_readiness():

{
  "date": "2026-07-07",
  "score": 78,
  "level": "READY",
  "feedback": "READY_TO_TRAIN",
  "recovery_time_min": 180,
  "acute_load": 302,
  "hrv_weekly_avg": 31,
  "factors": {
    "sleep": { "pct": 90, "rating": "GOOD" },
    "recovery_time": { "pct": 100, "rating": "GOOD" },
    "load_balance": { "pct": 65, "rating": "MODERATE" },
    "hrv": { "pct": 80, "rating": "GOOD" }
  }
}

get_daily_stats():

{
  "calendarDate": "2026-07-07",
  "totalSteps": 9432,
  "totalDistanceMeters": 7120,
  "totalKilocalories": 2568,
  "restingHeartRate": 52,
  "averageStressLevel": 34,
  "bodyBatteryMostRecentValue": 61
}

Troubleshooting

Privacy

Your data stays on your machine. This server only ever reads from Garmin Connect; the analyze_* tools cache what they fetch locally so trends can be computed offline. Nothing is uploaded anywhere, and there is no telemetry.

What is stored, and where:

Set GARMIN_OUTPUT_DIR to relocate the aggregate output (e.g. to a directory your agent reads from).

Retention: files are kept until you delete them. The cache only grows as you backfill or analyze more days; it is never pruned automatically.

How to wipe everything:

rm -rf ~/.garmin-activity ~/.garmin-mcp
# and, if you set a custom output dir:
rm -rf "$GARMIN_OUTPUT_DIR"

Deleting ~/.garmin-mcp/tokens also signs the server out; re-run the interactive login to use it again.

Development

uv run pytest                         # run tests with coverage
uv run pytest --cov-report=html       # HTML coverage report

License

Apache-2.0