Garmin MCP Server

Self-hosted Model Context Protocol server for Garmin Connect: multi-user, SQLite-backed history, HTTP/SSE for Claude custom connectors, optional Cloudflare Tunnel, and an agentic “sports companion” layer (bootstrap context, workout prompt, goals, flags).

Architecture

flowchart TD
    Claude[ClaudeConnector] --> Tunnel[CloudflareTunnel]
    Tunnel --> App[garmin-mcp]
    App --> MW[ApiKeyAndRateLimit]
    MW --> MCP[FastMCP_SSE]
    MCP --> Tools[Tools]
    Tools --> DB[(SQLite_WAL)]
    Sync[SyncService] --> Garmin[Garmin_API]
    Garmin --> Sync
    Sync --> DB

Prerequisites

• Docker and Docker Compose
• Garmin account (see Garmin MFA below)
• Cloudflare account if using Tunnel

Quick start

1. Clone this repository.
2. Copy config.example.yaml to config.yaml and fill in credentials, API keys, encryption secrets, and paths.
3. Set TUNNEL_TOKEN in the environment (e.g. .env next to docker-compose.yml) if using Cloudflare Tunnel.
4. Run docker compose up -d (or make up).
5. Open Claude → Settings → Connectors → Add custom connector: base URL https://<your-tunnel-host>/mcp (or your public URL), header X-API-Key: <user api_key>.

Configuration reference

| Field | Type | Default | Description | | --- | --- | --- | --- | | port | int | 8765 | HTTP port | | log_level | string | info | Logging level | | sync_interval_minutes | int | 30 | Background sync interval | | max_date_range_days | int | 90 | Max date span for tools | | users[].name | string | — | Username (must match /sync/{username}) | | users[].api_key | string | — | Secret for X-API-Key | | users[].db_path | path | — | SQLite file | | users[].backup_path | path | — | Backup directory (default example uses /data/backups/{name}/ outside the repo) | | users[].timezone | string | — | IANA timezone for display | | users[].rate_limit | int | 30 | Requests per minute per user | | users[].initial_sync_days | int | 365 | First full history pull | | users[].flag_rules | object | — | Thresholds for proactive flags |

Multi-user setup

Each users[] entry is isolated: its own Garmin credentials, API key, encrypted token file, SQLite DB, and backups.

Garmin MFA / Two-Factor Authentication

Garmin must have MFA disabled for automated login. Configure your account at:

https://account.garmin.com/account/security/

Rotating an API Key

1. Edit config.yaml and update the api_key value for the relevant user.
2. Run make down && make up to restart the container.
3. Update the X-API-Key header value in the Claude custom connector settings for that user.
4. Verify with make logs that the server restarted cleanly.

Sports companion: custom instructions

Add this to Claude’s custom instructions so every session bootstraps fresh data:

You are my personal sports coach with access to my Garmin data.
At the start of every conversation, call get_my_context to load
my current goals, recent training history, and latest data before
responding to anything.

MCP prompt: analyze_new_workout

Registered as a named prompt. Use when the user asks to analyze the latest workout or last run; it follows the structured steps documented in the server (context → activities → detail → reasoning → suggest → feeling).

Makefile

| Target | Purpose | | --- | --- | | make up | docker compose up -d | | make down | docker compose down | | make logs | Follow logs | | make test | Pytest suite | | make lint | Ruff check + format check | | make format | Apply Ruff formatter | | make sync | scripts/sync_all.py — POST /sync/{user} for each user (server must be running) | | make backup | POST /backup/all (set GARMIN_API_KEY to any user’s key) | | make shell | Shell in garmin-mcp container | | make validate | Compose config + config schema load |

Running tests

python -m venv .venv && .venv/bin/pip install -r requirements.txt
pytest tests/ -v

Troubleshooting

• Token expiry / auth errors: Check Garmin credentials; delete encrypted token file and restart; see logs.
• Port conflicts: Change port in config.yaml and compose port mapping.
• Tunnel not connecting: Verify TUNNEL_TOKEN and Cloudflare route to http://garmin-mcp:8765.
• make sync fails: The server must be reachable at http://127.0.0.1:8765 (or set GARMIN_MCP_URL). Start with make up first.
• Backups in repo: Prefer backup_path under /data/... (Docker volume). If you store backups inside the repo, extend .gitignore accordingly.

License

See LICENSE.