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.

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

For a Windows setup covering every dependency, both tunnels, ChatGPT, and troubleshooting, see INSTALLATION_HANDBOOK.md.

After the one-time setup on this Windows PC, start the local services and OpenAI tunnel with:

.\start-garmin-mcp.cmd

The launcher is safe to run again: healthy services are left running instead of duplicated. The OpenAI Runtime API key is requested in a separate window and kept only in process memory. Useful commands are status, restart, and stop:

.\start-garmin-mcp.cmd status
.\start-garmin-mcp.cmd restart
.\start-garmin-mcp.cmd stop

It deliberately does not expose the Garmin credential page. If the Garmin session must be linked again, first open a temporary HTTPS tunnel to port 3001 and then run:

.\start-garmin-mcp.cmd restart -LinkPublicBaseUrl https://<fresh-hostname>

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
• get_sleep, get_daily_summary, get_steps, get_heart_rate, get_hrv
• get_body_battery, get_stress, get_training_readiness
• list_activities, get_activity
• all 106 public get_*/count_* methods from pinned garminconnect==0.3.11, registered as explicit tools under their upstream names
• list_garmin_data_operations and get_garmin_data — discovery and bounded generic fallback
• download_activity_file, download_health_snapshot, download_workout_file — bounded file exports returned as MCP embedded resources
• disconnect_garmin

Garmin data tools are 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. The running server exposes 122 tools. See API_COVERAGE.md for upstream coverage, validation bounds, and deliberate exclusions.

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.