Garmin MCP Gateway

A multi-user, OAuth 2.1–protected gateway that lets a small trusted circle each connect their own Garmin Connect account to Claude (iOS, Android, Web, Desktop). It wraps the unmodified garmin_mcp worker and adds OAuth, per-user token isolation, and a reverse proxy.

Claude → POST /mcp (Bearer) → Gateway → 127.0.0.1:<port>/mcp (per-user garmin_mcp) → connect.garmin.com

Why

garmin_mcp is a great MCP server, but it's single-user and stdio-only: each person has to run it locally with their own Garmin tokens. This gateway makes it a remote MCP server any Claude client can connect to over HTTP, with a proper OAuth sign-in flow — so non-technical users just click "connect" and log in with their Garmin credentials, and never touch a terminal or a token file.

Related MCP server: Garmin Connect MCP Server

Features

• OAuth 2.1 — Authorization Code + PKCE (S256) with Dynamic Client Registration. Connect from any Claude client; no manual token wrangling.

• Password is never stored — used once to sign in with Garmin (MFA supported); only the resulting session tokens are persisted.

• Encrypted at rest — tokens sealed with AES-256-GCM; the DB is useless without GATEWAY_SECRET. Bearer tokens are stored only as SHA-256 hashes.

• Per-user isolation — each account gets its own garmin_mcp worker bound to 127.0.0.1, started on demand and reaped when idle.

• Hardened — one-time 10-min auth codes, CSRF on forms, per-IP/-token rate limits, the garmin_mcp worker pinned to a reviewed commit.

• Instructional landing page served on / and as a friendly fallback for unknown paths.

Quick start (Docker)

cp .env.example .env          # set GATEWAY_SECRET, PUBLIC_URL, pin GARMIN_MCP_REF
docker compose up -d --build

Put nginx in front for TLS + your domain (see nginx.conf.example), then add https://<your-domain>/mcp as a remote MCP server in Claude.

Local development

uv pip install -e ".[dev]"
uv run --extra dev pytest -q                 # run the test suite

# Run the gateway locally (no Garmin account needed to exercise the OAuth surface).
# garmin-mcp isn't on PATH locally, so point GARMIN_MCP_CMD at uvx.
GATEWAY_SECRET="$(openssl rand -base64 48)" \
PUBLIC_URL=http://localhost:8088 PORT=8088 DATA_DIR=./.localdata \
GARMIN_MCP_CMD="uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp" \
  uv run garmin-gateway

A .env file in the working directory is loaded automatically (real environment variables take precedence), so you can drop the same values there instead.

Connecting from Claude

1. In any Claude client: Settings → Connectors → Add custom connector, or in the CLI: claude mcp add --transport http garmin https://<your-domain>/mcp.

2. Claude opens the gateway's sign-in page — enter your Garmin Connect email + password (and an MFA code if prompted).

3. Done — your Garmin tools are now available in Claude.

Configuration

Set via environment (or .env). See .env.example.

Monitoring

Two helper scripts read the gateway's state (set GATEWAY_LOG_FILE so events are logged — it's in .env for local dev):

python scripts/status.py            # snapshot: how many people have a token,
                                    # devices connected, registered clients
python scripts/monitor.py           # live tail of structured events
                                    #   (mcp-request, worker-spawn, token-issued, …)
python scripts/monitor.py --all     # include garminconnect/urllib3 debug noise

The gateway also logs a stats event (accounts / tokens / people-with-token / clients / active-workers) on startup and whenever those counts change.

How it works

1. Claude registers a client (DCR) and starts OAuth 2.1 (Authorization Code + PKCE).

2. On the authorize page the user signs in with Garmin (email + password, + MFA if prompted). The gateway logs in via garminconnect, stores only the resulting tokens (encrypted), and discards the password.

3. Claude exchanges the code for a Bearer token.

4. On each /mcp call the gateway ensures the user's garmin_mcp worker is running (its own tokens, bound to 127.0.0.1) and reverse-proxies to it.

Security

• Garmin password is never persisted.

• Tokens encrypted at rest (AES-256-GCM); the DB is useless without GATEWAY_SECRET.

• Bearer tokens stored only as SHA-256 hashes.

• OAuth 2.1 PKCE (S256), one-time 10-min codes, CSRF on forms, per-IP/-token rate limits.

• Workers bind 127.0.0.1 only; garmin_mcp is pinned to a reviewed commit.

Deploy only on infrastructure you control and trust. Back up DATA_DIR; keep GATEWAY_SECRET separately.

Before you deploy

• Set a real random GATEWAY_SECRET (openssl rand -base64 48) — the app refuses to start with the placeholder from .env.example.

• Pin GARMIN_MCP_REF to a reviewed commit SHA — main is a floating ref that can change without notice (supply-chain).

• Access tokens have no expiry or auto-revocation — to revoke a device, delete its row from the access_tokens table.

• Run a manual end-to-end smoke test with a real Garmin account (including the MFA path) before connecting real users — the garminconnect login/token path is mocked in the automated tests.

License

MIT © 2026 Vaclav Slajs

Acknowledgements

Wraps the excellent garmin_mcp by Taxuspt, unmodified. Garmin and Garmin Connect are trademarks of Garmin Ltd.; this project is not affiliated with or endorsed by Garmin.