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

Activities

Daily Health

Sleep / Body Battery / HRV

Weight / Records / Fitness

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

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. Fork the repo and create a feature branch

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 automated via GitHub Actions:

# Bump version
npm version patch  # or minor, major

# Push the tag
git push --follow-tags

# GitHub Actions will:
# 1. Build the package
# 2. Publish to npm with provenance
# 3. Create a GitHub Release

License

AGPL-3.0