garmin-connect-mcp

MCP server for Garmin Connect. Access your activities, health stats, sleep data, FIT files, and more from Claude Code or any MCP client.

Why This Exists

In March 2026, Garmin changed their authentication API, breaking garth and python-garminconnect — the two most popular libraries for accessing Garmin data programmatically. Garth has been officially deprecated. Garmin added Cloudflare TLS fingerprinting that blocks all non-browser HTTP clients (Node.js fetch, Python requests, curl) from their API endpoints.

This project works around that by routing all API calls through a headless Playwright browser, inheriting a real Chrome TLS fingerprint. Authentication uses browser cookies captured from a manual login session.

Install

npm install -g @etweisberg/garmin-connect-mcp
npx playwright install chromium

Then register with Claude Code:

claude mcp add garmin -- npx @etweisberg/garmin-connect-mcp

You also need the Playwright MCP server for the login flow:

claude mcp add playwright -- npx @playwright/mcp@latest

Prerequisites

• Node.js 18+
• Playwright MCP server (for browser-based login)
• A Garmin Connect account with a synced device

Setup

1. Login

In Claude Code, call the garmin-login tool. It will walk you through:

1. Opening Garmin Connect in the Playwright browser
2. Logging in manually
3. Extracting cookies and CSRF token
4. Saving the session to ~/.garmin-connect-mcp/session.json

2. Verify

Call the check-session tool to confirm authentication works.

Session cookies expire after a few hours. Re-run the login flow when they do.

Available Tools

Session & Auth

Tool	Description
garmin-login	Returns login instructions for the Playwright MCP browser
check-session	Validates the saved session is still active
run-tests	Returns a test plan to verify all tools work

Activities

Tool	Description
list-activities	List activities with pagination
get-activity	Full activity summary (distance, duration, HR, calories)
get-activity-details	Time-series metrics (HR, cadence, elevation over time)
get-activity-splits	Lap/split data
get-activity-hr-zones	Heart rate time-in-zone breakdown
get-activity-polyline	Full-resolution GPS track
get-activity-weather	Weather conditions during activity
download-fit	Download original FIT file

Daily Health

Tool	Description
get-daily-summary	Steps, calories, distance, intensity minutes
get-daily-heart-rate	Heart rate data throughout the day
get-daily-stress	Stress levels throughout the day
get-daily-summary-chart	Combined wellness chart data
get-daily-intensity-minutes	Intensity minutes for a date
get-daily-movement	Movement/activity data
get-daily-respiration	Respiration rate data

Sleep / Body Battery / HRV

Tool	Description
get-sleep	Sleep score, duration, stages, SpO2
get-body-battery	Body battery charged/drained values
get-hrv	Heart rate variability data

Training & Recovery

Tool	Description
get-training-readiness	Training readiness score (sleep, recovery, load)
get-sleep-stats	Sleep statistics over a date range
get-hydration	Daily hydration/water intake data

Weight / Records / Fitness

Tool	Description
get-weight	Weight measurements over a date range
get-personal-records	All personal records with history
get-fitness-stats	Aggregated activity stats by type
get-vo2max	Latest VO2 Max estimate
get-hr-zones-config	Heart rate zone boundaries
get-power-zones	Power zone config for all sports
get-user-profile	User profile and settings

Calendar, Goals & Badges

Tool	Description
get-calendar	Monthly calendar with activities and events
get-goals	Active, future, or past fitness goals
get-badges	All earned badges/achievements
get-badge-leaderboard	Badge leaderboard among connections

Workouts

Tool	Description
list-workouts	List saved workouts
get-workout	Get workout details (steps, segments)
create-workout	Create a new workout (warmup, intervals, cooldown)
schedule-workout	Schedule a workout to a date (syncs to device)
delete-workout	Delete a workout
download-workout-fit	Download a workout as a FIT file

Architecture

Claude Code / MCP Client
        |
        | MCP (stdio)
        v
garmin-connect-mcp server
        |
        | page.evaluate(fetch(...))
        v
Headless Playwright Chromium
        |
        | HTTPS (real Chrome TLS fingerprint)
        v
connect.garmin.com/gc-api/*

All API calls are made from within a headless Chromium browser context via page.evaluate(fetch(...)). This inherits the real Chrome TLS fingerprint, bypassing Cloudflare's detection of non-browser clients.

Auth flow: Cookies + CSRF token are captured from a manual browser login (via the Playwright MCP server) and stored at ~/.garmin-connect-mcp/session.json. The headless browser loads these cookies on startup.

Why not direct HTTP? Cloudflare blocks Node.js fetch, Python requests, and even curl with a 403. Only requests from a real browser TLS stack are accepted.

Development

git clone https://github.com/etweisberg/garmin-connect-mcp.git
cd garmin-connect-mcp
npm install
npx playwright install chromium
npm run build

Scripts

Command	Description
npm run build	Compile TypeScript
npm run lint	Run ESLint
npm run format	Format with Prettier
npm run typecheck	Type check without emitting
npm test	Run integration tests (requires valid session)

Local Integration Testing

The standalone test suite (npm test) requires a valid Garmin session and hits the real API. Run it locally after authenticating:

npm test

Contributing

1. Create a feature branch off main
2. Make your changes
3. Run checks:

   npm run lint
   npm run format
   npm run typecheck
   npm run build
   

4. Test via Claude Code: The recommended way to verify your changes is through Claude Code. After building, call the run-tests MCP tool — it returns a test plan that exercises all 27 tools against the live Garmin API. Tell Claude to execute the plan and report results.
5. Open a PR against main

CI runs lint, format check, typecheck, and build on every PR. Integration tests run locally only (they require Garmin authentication that can't safely run in CI).

Releasing

Releases are fully automated. Every merge to main triggers the release workflow which:

1. Runs CI (lint, format, typecheck, build)
2. Bumps the patch version
3. Publishes to npm with provenance
4. Creates a GitHub Release

No manual version bumping or tagging needed — just merge your PR.

License

AGPL-3.0