@etweisberg/garmin-connect-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Ethan Weisberg
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,182 @@
+# 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](https://github.com/matin/garth) and [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) — the two most popular libraries for accessing Garmin data programmatically. Garth has been [officially deprecated](https://github.com/matin/garth/discussions/222). 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
+
+```bash
+npm install -g @etweisberg/garmin-connect-mcp
+npx playwright install chromium
+```
+
+Or register directly with Claude Code:
+
+```bash
+claude mcp add garmin -- npx @etweisberg/garmin-connect-mcp
+```
+
+### Prerequisites
+
+- Node.js 18+
+- [Playwright MCP server](https://www.npmjs.com/package/@playwright/mcp) (`claude mcp add playwright -- npx @playwright/mcp@latest`) — needed for the login flow
+
+## 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 |
+
+### 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-user-profile` | User profile and settings |
+
+## 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
+
+```bash
+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:
+
+```bash
+npm test
+```
+
+## Contributing
+
+1. Fork the repo and create a feature branch
+2. Make your changes
+3. Run checks:
+   ```bash
+   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:
+
+```bash
+# 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](LICENSE)

package/dist/auth.js

@@ -0,0 +1,80 @@
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getSessionDir, getSessionFile } from "./garmin-client.js";
+/**
+ * Login flow that uses the user's real Chrome profile to bypass Cloudflare.
+ * Falls back to a fresh Playwright browser if Chrome profile isn't found.
+ */
+export async function runLogin() {
+    let playwright;
+    try {
+        playwright = await import("playwright");
+    }
+    catch {
+        console.error("Playwright is required for login. Install it:\n" +
+            "  npm install playwright && npx playwright install chromium");
+        process.exit(1);
+    }
+    // Try to find Chrome user data dir for a real browser fingerprint
+    const chromeDataDir = join(homedir(), "Library/Application Support/Google/Chrome");
+    const useChromeProfile = existsSync(chromeDataDir);
+    let browser;
+    let context;
+    if (useChromeProfile) {
+        console.error("Launching with your Chrome profile (bypasses Cloudflare)...");
+        console.error("  Note: Close all Chrome windows first, or this will fail.\n");
+        browser = await playwright.chromium.launchPersistentContext(chromeDataDir, {
+            headless: false,
+            channel: "chrome",
+        });
+        context = browser;
+    }
+    else {
+        console.error("Launching Playwright Chromium...");
+        browser = await playwright.chromium.launch({ headless: false });
+        context = await browser.newContext();
+    }
+    const page = useChromeProfile
+        ? await context.newPage()
+        : await context.newPage();
+    console.error("Opening Garmin Connect...");
+    await page.goto("https://connect.garmin.com/app/activities");
+    console.error("\n  Log in to Garmin Connect in the browser window.\n" +
+        "  Once you see your activities list, press Enter here...\n");
+    await new Promise((resolve) => {
+        process.stdin.once("data", () => resolve());
+    });
+    // Extract CSRF token from <meta name="csrf-token">
+    const csrf = await page.evaluate("() => document.querySelector('meta[name=\"csrf-token\"]')?.content ?? null");
+    if (!csrf) {
+        console.error("Warning: could not find CSRF token. Make sure you're on the activities page.");
+    }
+    const cookies = useChromeProfile
+        ? await context.cookies()
+        : await context.cookies();
+    if (useChromeProfile) {
+        await context.close();
+    }
+    else {
+        await context.close();
+        await browser.close();
+    }
+    const sessionData = {
+        csrf_token: csrf ?? "",
+        cookies: cookies
+            .filter((c) => c.domain && c.domain.includes("garmin"))
+            .map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+        })),
+    };
+    const dir = getSessionDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = getSessionFile();
+    writeFileSync(file, JSON.stringify(sessionData, null, 2), { mode: 0o600 });
+    console.error(`\nSession saved to ${file}`);
+    console.error(`CSRF token: ${(csrf ?? "").substring(0, 20)}...`);
+    console.error(`Cookies: ${sessionData.cookies.length} saved`);
+}

package/dist/garmin-client.js

@@ -0,0 +1,171 @@
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SESSION_DIR = join(homedir(), ".garmin-connect-mcp");
+const SESSION_FILE = join(SESSION_DIR, "session.json");
+export function getSessionDir() {
+    return SESSION_DIR;
+}
+export function getSessionFile() {
+    return SESSION_FILE;
+}
+export function sessionExists() {
+    return existsSync(SESSION_FILE);
+}
+function loadSession() {
+    if (!existsSync(SESSION_FILE)) {
+        throw new Error(`No saved session found at ${SESSION_FILE}. Run: npx garmin-connect-mcp login`);
+    }
+    return JSON.parse(readFileSync(SESSION_FILE, "utf-8"));
+}
+/**
+ * Garmin Connect API client that routes requests through a headless Playwright
+ * browser to bypass Cloudflare TLS fingerprinting.
+ *
+ * The browser navigates to connect.garmin.com once (with saved cookies),
+ * then all API calls are made via page.evaluate(fetch(...)) from the
+ * browser context — inheriting the real Chrome TLS fingerprint.
+ */
+export class GarminClient {
+    page = null; // playwright Page
+    browser = null;
+    csrfToken;
+    cookies;
+    initialized = false;
+    displayName = null;
+    constructor(sessionPath) {
+        const session = sessionPath
+            ? JSON.parse(readFileSync(sessionPath, "utf-8"))
+            : loadSession();
+        this.csrfToken = session.csrf_token;
+        this.cookies = session.cookies;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        let playwright;
+        try {
+            playwright = await import("playwright");
+        }
+        catch {
+            throw new Error("Playwright is required. Install: npm install playwright && npx playwright install chromium");
+        }
+        this.browser = await playwright.chromium.launch({ headless: true });
+        const context = await this.browser.newContext();
+        // Load saved cookies into the browser context
+        await context.addCookies(this.cookies.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: "/",
+        })));
+        this.page = await context.newPage();
+        // Navigate to Garmin Connect to establish the Cloudflare session
+        await this.page.goto("https://connect.garmin.com/app/activities", {
+            waitUntil: "domcontentloaded",
+            timeout: 30000,
+        });
+        // Verify we got the CSRF token (page loaded successfully)
+        const csrf = await this.page.evaluate("() => document.querySelector('meta[name=\"csrf-token\"]')?.content ?? null");
+        if (csrf) {
+            this.csrfToken = csrf;
+        }
+        this.initialized = true;
+        console.error("Garmin browser session initialized");
+    }
+    async getDisplayName() {
+        if (this.displayName)
+            return this.displayName;
+        const settings = (await this.get("userprofile-service/userprofile/settings"));
+        this.displayName = settings.displayName;
+        if (!this.displayName) {
+            throw new Error("Could not resolve displayName from userprofile settings");
+        }
+        return this.displayName;
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.page = null;
+            this.initialized = false;
+        }
+    }
+    async get(path, params) {
+        await this.init();
+        let url = `/gc-api/${path}`;
+        if (params) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(params)) {
+                qs.set(k, String(v));
+            }
+            url += `?${qs.toString()}`;
+        }
+        const csrfToken = this.csrfToken;
+        const result = await this.page.evaluate(async ({ url, csrfToken }) => {
+            const resp = await fetch(url, {
+                headers: {
+                    "connect-csrf-token": csrfToken,
+                    Accept: "*/*",
+                },
+            });
+            const text = await resp.text();
+            return { status: resp.status, body: text };
+        }, { url, csrfToken });
+        if (result.status === 204 || (result.status === 200 && !result.body)) {
+            return { noData: true, status: result.status, path };
+        }
+        if (result.status !== 200) {
+            throw new Error(`Garmin API ${result.status}: ${path} — ${result.body}`);
+        }
+        return JSON.parse(result.body);
+    }
+    async getBytes(path) {
+        await this.init();
+        const url = `/gc-api/${path}`;
+        const csrfToken = this.csrfToken;
+        const result = await this.page.evaluate(async ({ url, csrfToken }) => {
+            const resp = await fetch(url, {
+                headers: {
+                    "connect-csrf-token": csrfToken,
+                    Accept: "*/*",
+                },
+            });
+            if (!resp.ok) {
+                return { status: resp.status, error: await resp.text(), data: null };
+            }
+            const buf = await resp.arrayBuffer();
+            // Convert to base64 to pass through page.evaluate boundary
+            const bytes = new Uint8Array(buf);
+            let binary = "";
+            for (let i = 0; i < bytes.length; i++) {
+                binary += String.fromCharCode(bytes[i]);
+            }
+            return { status: resp.status, error: null, data: btoa(binary) };
+        }, { url, csrfToken });
+        if (result.status !== 200 || !result.data) {
+            throw new Error(`Garmin API ${result.status}: ${path} — ${result.error ?? ""}`);
+        }
+        return Buffer.from(result.data, "base64");
+    }
+}
+// Singleton client for reuse across tool calls
+let _sharedClient = null;
+export function getSharedClient() {
+    if (!_sharedClient) {
+        _sharedClient = new GarminClient();
+    }
+    return _sharedClient;
+}
+// Clean up on process exit
+process.on("exit", () => {
+    _sharedClient?.close();
+});
+process.on("SIGINT", () => {
+    _sharedClient?.close();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    _sharedClient?.close();
+    process.exit(0);
+});

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+async function startMcpServer() {
+    const server = new McpServer({
+        name: "garmin-connect-mcp",
+        version: "0.1.0",
+    });
+    registerTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("garmin-connect-mcp server running on stdio");
+}
+async function main() {
+    const command = process.argv[2];
+    if (command === "login") {
+        const { runLogin } = await import("./auth.js");
+        await runLogin();
+    }
+    else {
+        await startMcpServer();
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/test.js

@@ -0,0 +1,210 @@
+/**
+ * Integration test suite for garmin-connect-mcp.
+ * Requires a valid session at ~/.garmin-connect-mcp/session.json.
+ * Run: npm test
+ */
+import { GarminClient } from "./garmin-client.js";
+const tests = [
+    // ── Session / Profile ──────────────────────────────────────────────
+    {
+        name: "check-session",
+        run: ({ client }) => client.get("userprofile-service/userprofile/user-settings/"),
+    },
+    {
+        name: "get-user-profile",
+        run: ({ client }) => client.get("userprofile-service/userprofile/user-settings/"),
+    },
+    // ── Activities ─────────────────────────────────────────────────────
+    {
+        name: "list-activities",
+        run: ({ client }) => client.get("activitylist-service/activities/search/activities", {
+            limit: 2,
+            start: 0,
+        }),
+    },
+    {
+        name: "get-activity",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}`),
+    },
+    {
+        name: "get-activity-details",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}/details`, {
+            maxChartSize: 100,
+            maxPolylineSize: 0,
+            maxHeatMapSize: 100,
+        }),
+    },
+    {
+        name: "get-activity-splits",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}/splits`),
+    },
+    {
+        name: "get-activity-hr-zones",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}/hrTimeInZones`),
+    },
+    {
+        name: "get-activity-polyline",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}/polyline/full-resolution/`),
+    },
+    {
+        name: "get-activity-weather",
+        run: ({ client, activityId }) => client.get(`activity-service/activity/${activityId}/weather`),
+    },
+    {
+        name: "download-fit",
+        run: ({ client, activityId }) => client.getBytes(`download-service/files/activity/${activityId}`),
+    },
+    // ── Daily Health ───────────────────────────────────────────────────
+    {
+        name: "get-daily-summary",
+        run: ({ client, displayName, today }) => client.get(`usersummary-service/usersummary/daily/${displayName}`, {
+            calendarDate: today,
+        }),
+    },
+    {
+        name: "get-daily-heart-rate",
+        run: ({ client, today }) => client.get("wellness-service/wellness/dailyHeartRate", { date: today }),
+    },
+    {
+        name: "get-daily-stress",
+        run: ({ client, today }) => client.get(`wellness-service/wellness/dailyStress/${today}`),
+    },
+    {
+        name: "get-daily-summary-chart",
+        run: ({ client, today }) => client.get("wellness-service/wellness/dailySummaryChart/", {
+            date: today,
+        }),
+    },
+    {
+        name: "get-daily-intensity-minutes",
+        run: ({ client, today }) => client.get(`wellness-service/wellness/daily/im/${today}`),
+    },
+    {
+        name: "get-daily-movement",
+        run: ({ client, today }) => client.get("wellness-service/wellness/dailyMovement", {
+            calendarDate: today,
+        }),
+    },
+    {
+        name: "get-daily-respiration",
+        run: ({ client, today }) => client.get(`wellness-service/wellness/daily/respiration/${today}`),
+    },
+    // ── Sleep, Body Battery, HRV ───────────────────────────────────────
+    {
+        name: "get-sleep",
+        run: ({ client, today }) => client.get("sleep-service/sleep/dailySleepData", {
+            date: today,
+            nonSleepBufferMinutes: 60,
+        }),
+    },
+    {
+        name: "get-body-battery",
+        run: ({ client }) => client.get("wellness-service/wellness/bodyBattery/messagingToday"),
+    },
+    {
+        name: "get-hrv",
+        run: ({ client, today }) => client.get(`hrv-service/hrv/${today}`),
+    },
+    // ── Weight ─────────────────────────────────────────────────────────
+    {
+        name: "get-weight",
+        run: ({ client, today, thirtyDaysAgo }) => client.get(`weight-service/weight/range/${thirtyDaysAgo}/${today}`, {
+            includeAll: "true",
+        }),
+    },
+    // ── Personal Records ───────────────────────────────────────────────
+    {
+        name: "get-personal-records",
+        run: ({ client, displayName }) => client.get(`personalrecord-service/personalrecord/prs/${displayName}`, {
+            includeHistory: "true",
+        }),
+    },
+    // ── Fitness Stats / Reports ────────────────────────────────────────
+    {
+        name: "get-fitness-stats",
+        run: ({ client, today, thirtyDaysAgo }) => client.get("fitnessstats-service/activity", {
+            aggregation: "daily",
+            startDate: thirtyDaysAgo,
+            endDate: today,
+            groupByActivityType: "true",
+            standardizedUnits: "true",
+            groupByParentActivityType: "false",
+            userFirstDay: "sunday",
+            metric: "duration",
+        }),
+    },
+    {
+        name: "get-vo2max",
+        run: ({ client, today }) => client.get(`metrics-service/metrics/maxmet/latest/${today}`),
+    },
+    {
+        name: "get-hr-zones-config",
+        run: ({ client }) => client.get("biometric-service/heartRateZones/"),
+    },
+];
+async function main() {
+    console.log("garmin-connect-mcp integration tests\n");
+    const client = new GarminClient();
+    const today = new Date().toISOString().slice(0, 10);
+    const thirtyDaysAgo = new Date(Date.now() - 30 * 86400000)
+        .toISOString()
+        .slice(0, 10);
+    // Bootstrap: resolve displayName
+    console.log("Bootstrapping...");
+    const settings = (await client.get("userprofile-service/userprofile/settings"));
+    const displayName = settings.displayName;
+    if (!displayName) {
+        console.error("FATAL: Could not resolve displayName from settings");
+        console.error("Response:", JSON.stringify(settings).slice(0, 500));
+        await client.close();
+        process.exit(1);
+    }
+    console.log(`  displayName: ${displayName}`);
+    // Bootstrap: get a recent activityId
+    const activities = (await client.get("activitylist-service/activities/search/activities", { limit: 1, start: 0 }));
+    const activityId = String(activities?.[0]?.activityId ?? "");
+    if (!activityId) {
+        console.error("FATAL: No activities found");
+        await client.close();
+        process.exit(1);
+    }
+    console.log(`  activityId: ${activityId}`);
+    console.log(`  date range: ${thirtyDaysAgo} → ${today}\n`);
+    const ctx = {
+        client,
+        displayName,
+        activityId,
+        today,
+        thirtyDaysAgo,
+    };
+    let passed = 0;
+    let failed = 0;
+    for (const test of tests) {
+        const start = Date.now();
+        try {
+            const result = await test.run(ctx);
+            if (result === undefined) {
+                throw new Error("undefined response");
+            }
+            const ms = Date.now() - start;
+            const noData = result && typeof result === "object" && "noData" in result;
+            console.log(`  PASS  ${test.name} (${ms}ms)${noData ? " [no data for date]" : ""}`);
+            passed++;
+        }
+        catch (e) {
+            const ms = Date.now() - start;
+            const msg = e instanceof Error ? e.message : String(e);
+            // Truncate long error messages
+            const short = msg.length > 120 ? msg.slice(0, 120) + "..." : msg;
+            console.log(`  FAIL  ${test.name} (${ms}ms) — ${short}`);
+            failed++;
+        }
+    }
+    console.log(`\nResults: ${passed} passed, ${failed} failed, ${passed + failed} total`);
+    await client.close();
+    process.exit(failed > 0 ? 1 : 0);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,442 @@
+import { z } from "zod";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getSharedClient, sessionExists, getSessionFile, } from "./garmin-client.js";
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResult(msg) {
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+function todayDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+function getClient() {
+    if (!sessionExists()) {
+        throw new Error("No Garmin session found. The user needs to run: npx garmin-connect-mcp login");
+    }
+    return getSharedClient();
+}
+export function registerTools(server) {
+    // ── garmin-login ────────────────────────────────────────────────────
+    server.tool("garmin-login", "Returns step-by-step instructions for authenticating with Garmin Connect. Requires the Playwright MCP server to be installed. After following these steps, ALWAYS call the check-session tool to verify the login worked.", {}, async () => {
+        const sessionFile = getSessionFile();
+        return textResult(`# Garmin Connect Login
+
+To authenticate, you need the Playwright MCP server installed (\`@playwright/mcp\`).
+
+## Steps (execute these in order):
+
+1. **Open Garmin Connect** using the Playwright MCP browser_navigate tool:
+   \`\`\`
+   browser_navigate → https://connect.garmin.com/app/activities
+   \`\`\`
+
+2. **Tell the user** to log in to Garmin Connect in the browser window that opened. Wait for them to confirm they are logged in and can see their activities.
+
+3. **Navigate to the activities page** (the login may redirect elsewhere):
+   \`\`\`
+   browser_navigate → https://connect.garmin.com/app/activities
+   \`\`\`
+
+4. **Extract the CSRF token** using browser_evaluate (NOT browser_run_code — the meta tag needs the page to be fully rendered):
+   \`\`\`javascript
+   () => {
+     const meta = document.querySelector('meta[name="csrf-token"]');
+     return meta ? meta.getAttribute('content') : 'NOT_FOUND';
+   }
+   \`\`\`
+   Save this value — you'll need it in step 6.
+
+5. **Extract cookies** using browser_run_code:
+   \`\`\`javascript
+   async (page) => {
+     const cookies = await page.context().cookies();
+     const garminCookies = cookies
+       .filter(c => c.domain && c.domain.includes('garmin'))
+       .map(c => ({ name: c.name, value: c.value, domain: c.domain }));
+     return JSON.stringify(garminCookies);
+   }
+   \`\`\`
+
+6. **Write the session file** to: ${sessionFile}
+   - Create the directory \`~/.garmin-connect-mcp/\` if it doesn't exist (mkdir -p)
+   - Combine the CSRF token from step 4 and cookies from step 5 into: \`{ "csrf_token": "<from step 4>", "cookies": <from step 5> }\`
+   - Write this JSON to the session file
+
+7. **IMPORTANT: Call the \`check-session\` tool** to verify the login worked.
+
+## Notes
+- Session cookies expire after a few hours — re-run this flow when they do.
+- The Playwright browser must stay open during steps 4-5 (don't close it before extracting).
+`);
+    });
+    // ── check-session ──────────────────────────────────────────────────
+    server.tool("check-session", "Check if the saved Garmin Connect session is still valid. MUST be called after garmin-login to verify authentication worked.", {}, async () => {
+        if (!sessionExists()) {
+            return errorResult("No session file found. Call the garmin-login tool for instructions.");
+        }
+        try {
+            const client = getClient();
+            const profile = await client.get("userprofile-service/userprofile/user-settings/");
+            return jsonResult({ status: "ok", profile });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return errorResult(`Session invalid or expired: ${msg}\nCall the garmin-login tool to re-authenticate.`);
+        }
+    });
+    // ── list-activities ────────────────────────────────────────────────
+    server.tool("list-activities", "List your Garmin Connect activities with pagination", {
+        limit: z
+            .number()
+            .default(20)
+            .describe("Max activities to return (1-100)"),
+        start: z.number().default(0).describe("Pagination offset"),
+    }, async ({ limit, start }) => {
+        const client = getClient();
+        const data = await client.get("activitylist-service/activities/search/activities", { limit, start });
+        return jsonResult(data);
+    });
+    // ── get-activity ───────────────────────────────────────────────────
+    server.tool("get-activity", "Get full activity summary (name, type, distance, duration, HR, calories, etc.)", {
+        activityId: z.string().describe("The activity ID"),
+    }, async ({ activityId }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}`);
+        return jsonResult(data);
+    });
+    // ── get-activity-details ───────────────────────────────────────────
+    server.tool("get-activity-details", "Get time-series metrics for an activity (HR, cadence, elevation, pace over time)", {
+        activityId: z.string().describe("The activity ID"),
+        maxChartSize: z
+            .number()
+            .default(10000)
+            .describe("Max data points to return"),
+    }, async ({ activityId, maxChartSize }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}/details`, { maxChartSize, maxPolylineSize: 0, maxHeatMapSize: 2000 });
+        return jsonResult(data);
+    });
+    // ── get-activity-splits ────────────────────────────────────────────
+    server.tool("get-activity-splits", "Get lap/split data for an activity", {
+        activityId: z.string().describe("The activity ID"),
+    }, async ({ activityId }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}/splits`);
+        return jsonResult(data);
+    });
+    // ── get-activity-hr-zones ──────────────────────────────────────────
+    server.tool("get-activity-hr-zones", "Get heart rate time-in-zone breakdown for an activity", {
+        activityId: z.string().describe("The activity ID"),
+    }, async ({ activityId }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}/hrTimeInZones`);
+        return jsonResult(data);
+    });
+    // ── get-activity-polyline ──────────────────────────────────────────
+    server.tool("get-activity-polyline", "Get full-resolution GPS track/polyline for an activity", {
+        activityId: z.string().describe("The activity ID"),
+    }, async ({ activityId }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}/polyline/full-resolution/`);
+        return jsonResult(data);
+    });
+    // ── get-activity-weather ───────────────────────────────────────────
+    server.tool("get-activity-weather", "Get weather conditions during an activity", {
+        activityId: z.string().describe("The activity ID"),
+    }, async ({ activityId }) => {
+        const client = getClient();
+        const data = await client.get(`activity-service/activity/${activityId}/weather`);
+        return jsonResult(data);
+    });
+    // ── get-user-profile ───────────────────────────────────────────────
+    server.tool("get-user-profile", "Get your Garmin Connect user profile and settings", {}, async () => {
+        const client = getClient();
+        const data = await client.get("userprofile-service/userprofile/user-settings/");
+        return jsonResult(data);
+    });
+    // ── download-fit ───────────────────────────────────────────────────
+    server.tool("download-fit", "Download the original FIT file for an activity. Returns the file path.", {
+        activityId: z.string().describe("The activity ID"),
+        outputDir: z
+            .string()
+            .default("./fit_files")
+            .describe("Directory to save the FIT file"),
+    }, async ({ activityId, outputDir }) => {
+        const client = getClient();
+        const zipBytes = await client.getBytes(`download-service/files/activity/${activityId}`);
+        mkdirSync(outputDir, { recursive: true });
+        // The response is a zip containing the .fit file
+        // Use a minimal zip extraction (ZIP local file header parsing)
+        const fitFile = extractFitFromZip(zipBytes, activityId);
+        if (fitFile) {
+            const outPath = join(outputDir, fitFile.name);
+            writeFileSync(outPath, fitFile.data);
+            return textResult(`Downloaded FIT file: ${outPath} (${fitFile.data.length} bytes)`);
+        }
+        // Fallback: save the raw zip
+        const zipPath = join(outputDir, `${activityId}.zip`);
+        writeFileSync(zipPath, zipBytes);
+        return textResult(`No .fit file found in archive. Saved raw zip: ${zipPath}`);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Daily Health
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-daily-summary", "Get daily summary: steps, calories, distance, intensity minutes, floors, etc.", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const displayName = await client.getDisplayName();
+        const data = await client.get(`usersummary-service/usersummary/daily/${displayName}`, { calendarDate: d });
+        return jsonResult(data);
+    });
+    server.tool("get-daily-heart-rate", "Get heart rate data throughout the day (resting HR, HR timeline)", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get("wellness-service/wellness/dailyHeartRate", { date: d });
+        return jsonResult(data);
+    });
+    server.tool("get-daily-stress", "Get stress level data throughout the day", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`wellness-service/wellness/dailyStress/${d}`);
+        return jsonResult(data);
+    });
+    server.tool("get-daily-summary-chart", "Get daily wellness summary chart data (combined health metrics)", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get("wellness-service/wellness/dailySummaryChart/", { date: d });
+        return jsonResult(data);
+    });
+    server.tool("get-daily-intensity-minutes", "Get intensity minutes earned for a date", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`wellness-service/wellness/daily/im/${d}`);
+        return jsonResult(data);
+    });
+    server.tool("get-daily-movement", "Get daily movement/activity data", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get("wellness-service/wellness/dailyMovement", {
+            calendarDate: d,
+        });
+        return jsonResult(data);
+    });
+    server.tool("get-daily-respiration", "Get respiration rate data for a date", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`wellness-service/wellness/daily/respiration/${d}`);
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Sleep, Body Battery, HRV
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-sleep", "Get sleep data: score, duration, stages, SpO2, HRV during sleep", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get("sleep-service/sleep/dailySleepData", {
+            date: d,
+            nonSleepBufferMinutes: 60,
+        });
+        return jsonResult(data);
+    });
+    server.tool("get-body-battery", "Get today's body battery charged/drained values", {}, async () => {
+        const client = getClient();
+        const data = await client.get("wellness-service/wellness/bodyBattery/messagingToday");
+        return jsonResult(data);
+    });
+    server.tool("get-hrv", "Get heart rate variability (HRV) data for a date", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`hrv-service/hrv/${d}`);
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Weight
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-weight", "Get weight measurements over a date range", {
+        startDate: z.string().describe("Start date YYYY-MM-DD"),
+        endDate: z.string().describe("End date YYYY-MM-DD"),
+    }, async ({ startDate, endDate }) => {
+        const client = getClient();
+        const data = await client.get(`weight-service/weight/range/${startDate}/${endDate}`, { includeAll: "true" });
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Personal Records
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-personal-records", "Get all personal records with history (fastest mile, longest run, etc.)", {}, async () => {
+        const client = getClient();
+        const displayName = await client.getDisplayName();
+        const data = await client.get(`personalrecord-service/personalrecord/prs/${displayName}`, { includeHistory: "true" });
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Fitness Stats / Reports
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-fitness-stats", "Get aggregated fitness stats by activity type over a date range", {
+        startDate: z.string().describe("Start date YYYY-MM-DD"),
+        endDate: z.string().describe("End date YYYY-MM-DD"),
+        aggregation: z
+            .string()
+            .default("daily")
+            .describe("Aggregation period: daily, weekly, monthly"),
+        metric: z
+            .string()
+            .default("duration")
+            .describe("Metric: duration, distance, calories"),
+    }, async ({ startDate, endDate, aggregation, metric }) => {
+        const client = getClient();
+        const data = await client.get("fitnessstats-service/activity", {
+            aggregation,
+            startDate,
+            endDate,
+            groupByActivityType: "true",
+            standardizedUnits: "true",
+            groupByParentActivityType: "false",
+            userFirstDay: "sunday",
+            metric,
+        });
+        return jsonResult(data);
+    });
+    server.tool("get-vo2max", "Get latest VO2 Max / fitness level estimate", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`metrics-service/metrics/maxmet/latest/${d}`);
+        return jsonResult(data);
+    });
+    server.tool("get-hr-zones-config", "Get your configured heart rate zone boundaries", {}, async () => {
+        const client = getClient();
+        const data = await client.get("biometric-service/heartRateZones/");
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Testing
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("run-tests", "Returns a test plan for verifying all garmin-connect-mcp tools work. Call each tool listed and report results.", {}, async () => {
+        return textResult(`# garmin-connect-mcp Test Plan
+
+Execute each tool below and verify it returns valid data (not an error).
+Report results as a table: tool name, status (PASS/FAIL), notes.
+
+## Prerequisites
+1. Call check-session first. If it fails, call garmin-login to authenticate.
+
+## Tests (run in order)
+
+### Session
+- check-session -> should return { status: "ok", profile: { ... } }
+
+### Activities
+- list-activities (limit: 3) -> should return array of 3 activities
+- get-activity (use activityId from above) -> should return activity object with summaryDTO
+- get-activity-details (same ID) -> should return metricDescriptors + metrics
+- get-activity-splits (same ID) -> should return lapDTOs array
+- get-activity-hr-zones (same ID) -> should return array of 5 zones with secsInZone
+- get-activity-polyline (same ID) -> should return polyline data (may fail for indoor activities)
+- get-activity-weather (same ID) -> should return weather data (may fail for indoor activities)
+
+### Daily Health (use today's date or omit for default)
+- get-daily-summary -> should return steps, calories, distance fields
+- get-daily-heart-rate -> should return heartRateValues array
+- get-daily-stress -> should return stressValuesArray
+- get-daily-summary-chart -> should return chart data object
+- get-daily-intensity-minutes -> should return intensity minutes data
+- get-daily-movement -> should return movement data
+- get-daily-respiration -> should return respiration data
+
+### Sleep / Body Battery / HRV
+- get-sleep -> should return sleep score, duration, sleep stages
+- get-body-battery -> should return charged/drained values
+- get-hrv -> should return HRV data (may return { noData: true } if no overnight data yet)
+
+### Weight / Records / Fitness
+- get-weight (startDate: 30 days ago, endDate: today) -> should return weight data (may be empty array)
+- get-personal-records -> should return personal records with history
+- get-fitness-stats (startDate: 30 days ago, endDate: today) -> should return activity stats by type
+- get-vo2max -> should return VO2 max estimate
+- get-hr-zones-config -> should return HR zone boundaries
+- get-user-profile -> should return user settings with userData
+
+### Download
+- download-fit (use activityId from list, outputDir: /tmp/garmin-test) -> should save .fit file and return path
+
+## Expected Acceptable Failures
+- get-activity-polyline / get-activity-weather may fail for indoor activities (no GPS/weather data)
+- get-hrv may return { noData: true } for today if overnight data hasn't synced yet
+- get-weight may return empty array if no weight entries recorded
+
+## Report
+Present results as a markdown table: | Tool | Status | Notes |
+Count total passed vs failed at the end.`);
+    });
+}
+/**
+ * Minimal zip extraction — finds and extracts the first .fit file from a zip buffer.
+ * Avoids needing a zip library dependency.
+ */
+function extractFitFromZip(buf, activityId) {
+    // ZIP local file header signature: PK\x03\x04
+    let offset = 0;
+    while (offset < buf.length - 30) {
+        if (buf[offset] === 0x50 &&
+            buf[offset + 1] === 0x4b &&
+            buf[offset + 2] === 0x03 &&
+            buf[offset + 3] === 0x04) {
+            const compressionMethod = buf.readUInt16LE(offset + 8);
+            const compressedSize = buf.readUInt32LE(offset + 18);
+            const uncompressedSize = buf.readUInt32LE(offset + 22);
+            const nameLength = buf.readUInt16LE(offset + 26);
+            const extraLength = buf.readUInt16LE(offset + 28);
+            const name = buf.toString("utf-8", offset + 30, offset + 30 + nameLength);
+            const dataStart = offset + 30 + nameLength + extraLength;
+            if (name.endsWith(".fit") && compressionMethod === 0) {
+                // Stored (no compression) — just slice the data
+                const data = buf.subarray(dataStart, dataStart + uncompressedSize);
+                return { name: `${activityId}.fit`, data: Buffer.from(data) };
+            }
+            if (name.endsWith(".fit") && compressionMethod === 8) {
+                // Deflate compressed — use Node's zlib
+                const { inflateRawSync } = await_import_zlib();
+                const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+                const data = inflateRawSync(compressed);
+                return { name: `${activityId}.fit`, data };
+            }
+            // Skip to next file header
+            offset = dataStart + compressedSize;
+        }
+        else {
+            offset++;
+        }
+    }
+    return null;
+}
+function await_import_zlib() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require("node:zlib");
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@etweisberg/garmin-connect-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Garmin Connect — access activities, metrics, and FIT files via Claude Code",
+  "type": "module",
+  "bin": {
+    "garmin-connect-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/etweisberg/garmin-connect-mcp.git"
+  },
+  "homepage": "https://github.com/etweisberg/garmin-connect-mcp#readme",
+  "scripts": {
+    "build": "tsc && chmod 755 dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "tsx src/test.ts",
+    "lint": "eslint .",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "playwright": "^1.52.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "keywords": [
+    "garmin",
+    "garmin-connect",
+    "mcp",
+    "model-context-protocol",
+    "fit",
+    "fitness",
+    "claude"
+  ],
+  "license": "AGPL-3.0"
+}