Garmin → Claude MCP server

Analyze your own Garmin Connect data — activities, sleep, HRV, Body Battery, training readiness — right inside Claude Desktop.

A fully local, read-only MCP server that lets you analyze your own Garmin Connect data in Claude Desktop. The server runs as a local child process of Claude Desktop and talks to it over stdio.

Guiding principles

• 100% local — nothing is hosted or exposed to the network (stdio).

• Read-only — there is no write endpoint to Garmin.

• No third party — the only network contact is Garmin. No telemetry, no external logging.

• Passwordless at runtime — the password is never stored; after the one-time login only local tokens are used.

Related MCP server: Garmin Health MCP Server

Requirements

• Node.js ≥ 20 (tested with Node 22 LTS), npm.

• A Garmin Connect account.

Setup (4 steps)

# 1) Install dependencies
npm install

# 2) Milestone test: does the client get through Garmin's Cloudflare protection?
npm run smoke
#    Expectation: "Status 200" and "Challenge: no".

# 3) One-time interactive login (prompts for email, hidden password, MFA if enabled)
npm run login
#    Creates ~/.garmin-mcp/tokens.json (mode 0600). The password is NOT stored.

# 4) Compile TypeScript to build/
npm run build

Connecting Claude Desktop

Claude Desktop → Settings → Developer → Edit Config. Add the server with its absolute path (claude_desktop_config.json):

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-mcp/build/mcp/server.js"]
    }
  }
}

Then restart Claude Desktop. Try it in chat, e.g.:

"Am I logged in to Garmin? Use whoami." "Show me my daily summary and my recent activities."

Updating

git pull
npm install      # dependencies may have changed
npm run build    # build/ is not part of the repo

Then restart Claude Desktop. It runs the server as a child process, and a running instance keeps the code it loaded at startup — so an update only takes effect after a restart.

Your login survives an update: ~/.garmin-mcp/tokens.json is untouched and the path in claude_desktop_config.json stays the same. Only re-run npm run login if a tool actually reports 🔒 Not logged in.

Available tools

13 read-only tools. Date parameters are YYYY-MM-DD (default = today); ranges default to the last ~4 weeks. Several tools take a metrics[] / include[] selector, so one tool covers many data types (this keeps the tool list small for good tool selection). Long time series in responses are truncated to stay compact.

How it works

The server registers each Garmin data method as an MCP tool and talks to Claude Desktop over stdio. Every call goes through a generic connectapi() request to connectapi.garmin.com with a bearer token, sent via cycletls so the TLS fingerprint looks like a real browser (Garmin sits behind Cloudflare).

Authentication happens once (npm run login): a login cascade — mobile iOS JSON login first, the classic widget/CSRF flow as fallback — yields a CAS service ticket, which is exchanged in Garmin's DI-OAuth2 flow for an access + refresh token. The tokens are cached locally and the access token is refreshed automatically on expiry; your password is never stored.

Security model

• The password is never stored — it is only used for the one-time login.

• Tokens live at ~/.garmin-mcp/tokens.json with file mode 0600 (only you can read them).

• The access token is renewed automatically via the refresh token when it expires.

• Read-only: there is no code path that changes anything on Garmin.

• No telemetry, no external logging. Diagnostics go to stderr only (never over the stdio MCP channel).

Architecture (layers)

• src/http/impersonate.ts — TLS impersonation via cycletls (JA3 fingerprint) + cookie jar, so Garmin's bot protection lets us through.

• src/http/smoke.ts — milestone test against sso/embed.

• src/garmin/auth.ts — login cascade (mobile iOS JSON login → widget/CSRF fallback) + MFA + DI-OAuth2 ticket exchange + refresh.

• src/garmin/tokens.ts — local token cache (0600).

• src/garmin/client.ts — generic connectapi() + typed, read-only data methods.

• src/mcp/server.ts — MCP server and tool registration; served over stdio via serveStdio (MCP TypeScript SDK v2), which answers both 2025-era clients such as Claude Desktop and the 2026-07-28 protocol revision.

• src/cli/login.ts — one-time interactive login.

Development

npm run build     # tsc -> build/
npm test          # unit tests for the pure helpers (no network, no credentials)
npm run smoke     # milestone test against Garmin's Cloudflare (needs network)
npm run login     # one-time interactive login (needs your credentials)
npm start         # run the built server directly (normally Claude Desktop does this)

CI (.github/workflows/ci.yml) runs npm ci, npm run build and npm test on Node 22. build doubles as the type-check. smoke and login are deliberately excluded — they need live Garmin access and real credentials, and would be flaky.

npm test covers the pure helpers only (trimLongArrays, decodeJwtExp, toSearchParams) and never imports the MCP SDK, so a green test run says nothing about tool registration. After changing tools or upgrading dependencies, probe the server over stdio. No Garmin credentials are needed — registration and argument validation both happen before any authentication:

npm run build
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node build/mcp/server.js

Expect an initialize reply plus a tools/list reply containing all 13 tools with their input schemas. To also confirm that argument validation still bites, add one more line to the printf above — it should come back as a tool result with "isError": true and an Input validation error: … text, not as a login error:

'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_activity","arguments":{"activityId":"not-a-number"}}}' \

Dependencies are updated by Dependabot (.github/dependabot.yml, weekly). The npm updates arrive as one grouped PR that can include major versions, so read its package.json diff before merging, and run the stdio probe above rather than trusting a green build alone.

Maintenance & risks (named honestly)

This uses Garmin's unofficial internal API, ported from the open-source Python package python-garminconnect. Expected breakage points and how to fix them:

• Unofficial API — endpoint paths can change. On errors, compare the paths in src/garmin/client.ts against the current python-garminconnect source.

• JA3 / User-Agent — on a 403 or a "Just a moment …" Cloudflare page, update the JA3/User-Agent pair in src/http/impersonate.ts to a current Chrome (both together).

• Client ids — the DI-OAuth2 client ids (GARMIN_CONNECT_MOBILE_ANDROID_DI_*) rotate; update the list in src/garmin/auth.ts on auth errors.

• garth is discontinued — the previously common auth library garth is no longer maintained; the authoritative reference is python-garminconnect.

• Keep the token folder private — ~/.garmin-mcp/ holds valid session tokens; don't share it, don't commit it.

• Terms of service — access via the unofficial API may be in tension with Garmin's terms of service. Intended for private personal use with your own data.

Troubleshooting

• 403 or a "Just a moment …" page — Garmin's Cloudflare is blocking the TLS fingerprint. Update the JA3/User-Agent pair in src/http/impersonate.ts to a current Chrome (both together), then re-run npm run smoke.

• 🔒 Not logged in / session expired — run npm run login again.

• ⏳ rate limited (HTTP 429) — Garmin is throttling; wait a bit and retry.

• First run is slow / cycletls errors — cycletls downloads a small Go helper binary on first use; make sure it can execute and isn't blocked by the OS.

• Calls hang right after an update — the previous server process may have left its cycletls Go helper behind. Check with pgrep -fl cycletls and clear it with pkill -f cycletls; the next call starts a fresh one.

Re-login

If tools report 🔒 Not logged in (token expired/invalid):

npm run login

License

MIT © Marcel Fortmann

Disclaimer

This is an unofficial, community project. It is not affiliated with, endorsed by, or sponsored by Garmin. Garmin® and Garmin Connect™ are trademarks of Garmin Ltd. or its subsidiaries.