garmin-connect

This Garmin Connect MCP Server provides a rich set of tools to access and analyze your Garmin Connect data through Claude and other LLM interfaces. It exposes 22 tools across categories like Activities, Analysis, Health & Wellness, Training, User Profile, Challenges & Goals, Devices & Gear, Weight Management, and Other. In addition to the tools, the server registers MCP Resources such as an Athlete Profile, Training Readiness, and Daily Health context, plus a library of prompts to guide common queries (e.g., training analysis, sleep quality, and health summaries). You can ask Claude to run analyses, pull detailed activity data, compare workouts, fetch health metrics, and surface personal records and device information, all via natural language prompts.

Prerequisites:

• Python 3.11+ and uv installed, or Docker installed
• Access to Garmin Connect credentials for authentication

Option A: Install and run with UV

1. Ensure dependencies are installed (Python and uv):
   • Install Python 3.11+ from python.org
   • Install uv: pip install uv or follow the UV installation guide for your OS
2. Clone or download the garmin-connect-mcp project and navigate to its directory:
   • cd garmin-connect-mcp
3. Run the MCP server with UV using the directory path to your project and the package name you want to expose:
   • uv run --directory /ABSOLUTE/PATH/TO/garmin-connect-mcp garmin-connect-mcp
4. Follow the authentication flow to connect your Garmin Connect account. Tokens will be stored and refreshed automatically.

Option B: Install and run with Docker

1. Install Docker on your system.
2. Pull the latest image:
   • docker pull ghcr.io/eddmann/garmin-connect-mcp:latest
3. Run the container and expose the MCP server (you may set environment variables for credentials as needed inside the container or via mounted volumes):
   • docker run -it --rm
     -v "/ABSOLUTE/PATH/TO/.garminconnect:/root/.garminconnect"
     -v "/ABSOLUTE/PATH/TO/garmin-connect-mcp.env:/app/.env"
     ghcr.io/eddmann/garmin-connect-mcp:latest
4. The container will prompt for MFA on first run if required and persist tokens as configured. Ensure you mount token directories to avoid repeated MFA prompts.

Configuration & Credentials

• OAuth tokens and credentials are stored in the configured path (e.g., ~/.garminconnect or mounted volumes).
• For Docker with MFA, persist tokens by mounting a host directory to the container (recommended).

Tips and common issues:

• MFA prompts: If your Garmin account has MFA enabled, you may be prompted for a code on first run. Persist tokens to avoid repeated MFA prompts across restarts by mounting a token directory (e.g., ~/.garminconnect or a dedicated Docker volume).
• Token persistence: When using Docker, volume mounts are essential for token persistence and MFA workflow efficiency.
• Credentials format: You can provide credentials via an interactive setup or by placing them in a .env file as GARMIN_EMAIL and GARMIN_PASSWORD.
• Claude integration: The MCP Resources (athlete profile and daily health) provide ongoing context for prompts; you can craft queries around readiness checks, health summaries, and training analysis with these resources in mind.
• Pagination: Some list-returning tools paginate results (e.g., activities, health data). Be aware of default limits (10 activities, 7 health data items) and use filters to refine results.
• Environment paths: Replace /ABSOLUTE/PATH/TO/... with real absolute paths on your host machine for UV directory or Docker volume mappings.