Garmin MCP

Project status (2026-08-23): personal-tunnel implementation; local smoke tests pass. Do not enable friend access or public MCP ingress. Real Garmin credentials remain blocked until the operator explicitly approves the separate public HTTPS link-web tunnel and completes the live-test checklist in PERSONAL_TUNNEL_RUNBOOK.md.

Multi-user, read-only MCP resource server that wraps cyberjunky/python-garminconnect. It exposes authenticated Garmin data without accepting a user ID as a tool argument.

Security model

The bullets below describe the original design intent. They are not yet all proven by the current implementation; the known gaps and required acceptance tests are tracked in DESIGN_DRAFT.md.

• MCP bearer tokens are verified separately from Garmin authentication. Production OIDC validates signature, issuer, audience, expiry, required scopes, and uses the verified sub claim.

• Garmin email, password, and MFA codes exist only during their request. They are not persisted or logged. Uvicorn access logging is disabled.

• Only python-garminconnect's serialized session JSON is stored, encrypted with AES-256-GCM and authenticated against the owning principal so ciphertext cannot be moved between users.

• MFA clients are process-local, single-use, owner-bound, and expire after five minutes.

• Connection URLs place their signed one-time state in the fragment. External JavaScript clears the fragment and moves state into a POST body, keeping it out of HTTP and proxy access logs.

• Disconnect deletes the local encrypted tokens. This does not revoke a token already issued by Garmin; revoke access in Garmin account security settings if compromise is suspected.

Related MCP server: garmin-mcp

Personal ChatGPT tunnel mode

The personal setup deliberately uses two listeners:

• SERVER_ROLE=mcp on loopback port 3000. Only OpenAI Secure MCP Tunnel may reach this port.

• SERVER_ROLE=link-web on loopback port 3001. A separate HTTPS tunnel may expose only this listener so a phone can enter Garmin credentials without exposing the MCP endpoint.

AUTH_MODE=tunnel has one configured TUNNEL_PRINCIPAL_ID; it is not a multi-user mode. The OpenAI tunnel is the authentication boundary, and the server refuses combined mode or a non-loopback bind unless container isolation is explicitly enabled. See PERSONAL_TUNNEL_RUNBOOK.md for the end-to-end setup.

Run locally

Requires Python 3.12+, PostgreSQL 17, and uv.

cp .env.example .env
# Fill secrets, then for local-only bearer authentication set AUTH_MODE=development.
uv sync --all-extras
psql "$DATABASE_URL" -f migrations/001_initial.sql
uv run garmin-mcp

Or run docker compose up --build after creating .env. Compose publishes both application ports to 127.0.0.1 only and does not publish PostgreSQL. The MCP endpoint is /mcp; the health endpoint is /healthz. In development mode the bearer value itself is the local user ID. Never expose development mode beyond loopback.

MCP tools

• get_connection_status

• connect_garmin — returns a ten-minute, single-use browser URL

• get_profile

• disconnect_garmin

The current Garmin data tool is read-only. disconnect_garmin mutates only local connection state by deleting the stored session. Account credentials are entered only into the browser linking page, never supplied as MCP tool arguments. Health/activity tools have not been implemented yet.

Validation

uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run pip-audit

Do not put real Garmin credentials in CI. Any future live test must use a dedicated account and an explicit integration-test marker.