Garmin Connect MCP 服务器

garmin-connect-mcp

An MCP server that connects Claude to your Garmin Connect data — steps, heart rate, sleep, activities, workouts, hydration, weight, and golf summaries — plus a personal lift log and the ability to push structured strength workouts to Garmin Connect (and from there to the watch). 26 tools.

Runs in two modes from one codebase:

Tools

Date inputs are optional YYYY-MM-DD strings defaulting to today (or last night for sleep tools).

Default date and timezone. Tools that default date to "today" (log-lift, the Garmin daily tools) resolve the calendar day in LIFT_TIMEZONE (falling back to TZ, then the runtime's zone). Set this to your IANA zone (e.g. America/New_York) so a late-night log lands on the correct local day rather than UTC.

The lift log is user-written personal data, stored in its own SQLite database (LIFT_DB_PATH), kept entirely separate from Garmin-sourced data and from the OAuth auth database. Your real lift history lives only on your server's volume and is never committed to this repo.

Quickstart: stdio mode (Claude Code)

git clone https://github.com/PepperoniRollz/garmin-connect-mcp.git
cd garmin-connect-mcp
npm ci && npm run build

Store your Garmin credentials in the OS credential store (macOS shown; Windows Credential Manager and Linux libsecret are also supported — the server prints per-platform instructions if credentials are missing):

security add-generic-password -s garmin-connect-mcp -a username -w 'you@example.com'
security add-generic-password -s garmin-connect-mcp -a password -w 'your-garmin-password'

Then register it with Claude Code:

claude mcp add garmin -- node /path/to/garmin-connect-mcp/dist/index.js

GARMIN_USERNAME / GARMIN_PASSWORD environment variables take precedence over the credential store when both are set.

Remote connector mode (claude.ai web / desktop / mobile)

In HTTP mode the server hosts its own OAuth 2.1 authorization server (PKCE S256 only, dynamic client registration, rotating refresh tokens) so claude.ai can connect securely. You deploy it behind a TLS-terminating reverse proxy; only you can authorize access, via a single owner password.

                      ┌─────────────────────────────────────────┐
                      │ Your server                             │
 Claude (Anthropic    │  ┌────────┐      ┌────────────────────┐ │
 cloud) ── HTTPS ────▶│  │ Caddy  │─────▶│ garmin-connect-mcp │ │
                      │  │ :443   │      │ http mode :8081    │ │
                      │  └────────┘      │ (localhost only)   │ │
                      │   auto-TLS       └─────────┬──────────┘ │
                      └────────────────────────────┼────────────┘
                                                   ▼
                                            Garmin Connect API

Deploy (Docker Compose + Caddy)

1. DNS: point a subdomain (e.g. garmin-mcp.example.com) at your server. If you use Cloudflare, "DNS only" (gray cloud) is the verified configuration; the proxied mode is untested with long-lived SSE streams.
2. Owner password hash (the plaintext never appears in any config):
   复制

   npm run hash-password
   

3. Configure: copy the repo to the server, then
   复制

   cp .env.deploy.example .env && chmod 600 .env
   

   Fill in GARMIN_USERNAME, GARMIN_PASSWORD, GARMIN_MCP_PUBLIC_URL (e.g. https://garmin-mcp.example.com/mcp — path must be /mcp), and SERVER_OWNER_PASSWORD_HASH (single-quoted — bcrypt hashes contain $, which Docker Compose otherwise interpolates).
4. Run:
   复制

   docker compose up -d --build
   

   The container publishes to 127.0.0.1:8081 only.
5. Caddy site block (Caddy obtains the Let's Encrypt certificate automatically):
   复制

   garmin-mcp.example.com {
       reverse_proxy localhost:8081
       encode gzip
   }
   

   scripts/phase4-root-setup.sh automates this (plus compose-plugin install) with a validate-before-reload safety path; review it first.
6. Connect: claude.ai → Settings → Connectors → Add custom connector → https://garmin-mcp.example.com/mcp. Claude discovers the OAuth metadata, registers itself, and sends you to the login page; enter the owner password to approve. The same connector works on Claude mobile.

Verify a deployment

curl https://garmin-mcp.example.com/healthz        # → {"status":"ok"}
curl -X POST https://garmin-mcp.example.com/mcp    # → 401 + WWW-Authenticate
OAUTH_TEST_PASSWORD=... npx tsx scripts/oauth-flow-test.ts https://garmin-mcp.example.com

Environment variables

The server never reads .env files itself — provide real environment variables (Docker Compose env_file:, systemd EnvironmentFile=, shell).

Security notes

• Unofficial API disclaimer: this project uses the unofficial garmin-connect client. Garmin does not sanction it; it can break without notice, and aggressive use could affect your Garmin account. Use at your own risk.
• Single-user model: one deployment serves exactly one Garmin account. OAuth protects access to the server; whoever completes the owner login sees that account's data. There is no multi-tenancy.
• Credential handling: Garmin credentials live in env vars (HTTP mode) or the OS credential store (stdio). The owner password exists only as a bcrypt hash. OAuth tokens and codes are stored as SHA-256 hashes in SQLite and survive restarts; refresh tokens rotate on use.
• Never expose HTTP mode without auth. See SECURITY.md.
• Datacenter-IP caveat: Garmin throttles (429) fresh logins from cloud provider IPs. Seed the deployed token cache with tokens minted on a residential connection: run the server locally once, then copy oauth1_token.json / oauth2_token.json from your TOKEN_CACHE_DIR into the server's token volume. Cached tokens refresh without re-triggering the throttle.

Development

npm run dev        # run from source (tsx)
npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit (src + scripts)
npm run lint       # gts (Google TypeScript style)
npm test           # e2e: OAuth flow + session lifecycle, no Garmin account needed

Architecture and roadmap: docs/SPEC.md.

License

MIT