Garmin Connect MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to your Garmin Connect health and fitness data. Ask Claude, ChatGPT, OpenCode, or any MCP-compatible client about your workouts, sleep, heart rate, and more -- using natural language.

Built on python-garminconnect and the MCP Python SDK.

Features

29 tools across 6 categories, giving your AI assistant access to:

Category	Tools	Examples
Health	5	Daily summary, heart rate, sleep stages, stress, body battery
Activities	4	Recent workouts, search by date/type, detailed splits
Body	3	Weight trends, body composition, hydration tracking
Fitness	6	Training readiness, VO2 Max, HRV, race predictions, endurance score
Devices	6	Device info, step trends, personal records, SpO2, respiration, goals
Export	5	Download FIT, GPX, TCX, KML, and CSV files

Quick Start

Prerequisites

• Python 3.10+
• uv package manager
• A Garmin Connect account with a paired device

1. Clone and install

git clone https://github.com/JohanBellander/garmin-mcp-server.git
cd garmin-mcp-server
uv sync

2. Authenticate with Garmin

Run the one-time setup to save your OAuth tokens:

uv run garmin-mcp-setup

You'll be prompted for your email, password, and MFA code (if enabled). Tokens are saved to ~/.garminconnect/ and last approximately one year -- you won't need to re-authenticate until they expire.

3. Connect to your AI assistant

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/garmin-mcp-server",
        "run",
        "garmin-mcp-server"
      ]
    }
  }
}

OpenCode

Add to your .opencode.json MCP config:

{
  "mcp": {
    "garmin": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/garmin-mcp-server",
        "run",
        "garmin-mcp-server"
      ]
    }
  }
}

Any MCP Client

The server uses STDIO transport. Point your client at:

uv --directory /path/to/garmin-mcp-server run garmin-mcp-server

Example Conversations

Once connected, you can ask your AI assistant things like:

• "How did I sleep last night?"
• "Show me my runs from the past two weeks"
• "What's my training readiness today?"
• "Compare my resting heart rate over the last 7 days"
• "Download the GPX file for my last bike ride"
• "What are my race predictions for a half marathon?"
• "How many steps have I averaged this month?"

Available Tools

Health Data

Tool	Description
get_daily_summary	Steps, distance, calories, floors climbed, active minutes for a date
get_heart_rate	Resting HR, min/max, heart rate zone breakdown
get_sleep	Sleep duration, stages (deep/light/REM/awake), sleep score
get_stress	All-day stress levels, average, duration by category
get_body_battery	Energy reserve levels throughout the day

Activities

Tool	Description
get_recent_activities	Most recent workouts with key metrics
get_activities_by_date	Activities in a date range, filterable by type (running, cycling, etc.)
get_activity_details	Full detail for a specific activity: pace, HR zones, elevation, training effect
get_activity_splits	Per-split/lap breakdown: pace, distance, HR, elevation

Body Composition

Tool	Description
get_weight	Weight measurements, BMI, body fat %
get_body_composition	Weight, body fat, muscle mass, bone mass, body water
get_hydration	Daily water intake and progress toward goal

Fitness Metrics

Tool	Description
get_training_readiness	Readiness score, HRV status, sleep quality, recovery time
get_vo2max	Estimated VO2 Max for running and cycling
get_training_status	Training load and status classification
get_race_predictions	Predicted times for 5K, 10K, half marathon, and marathon
get_hrv	Heart Rate Variability: status, weekly average, baseline
get_endurance_score	Aerobic fitness score over time

Export & Download

Tool	Description
download_activity_fit	Original FIT file (as ZIP) -- raw sensor data
download_activity_gpx	GPX track -- GPS coordinates for mapping
download_activity_tcx	TCX file -- GPS + HR + cadence
download_activity_kml	KML file -- for Google Earth
download_activity_csv	CSV file -- tabular data for spreadsheets

Additional Tools

Tool	Description
get_devices	Connected devices: model, firmware, battery, last sync
get_daily_steps	Step counts per day over a date range
get_personal_records	Personal bests across all activities
get_respiration	Breathing rate: waking, sleeping, high, low
get_spo2	Blood oxygen saturation readings
get_goals	Active fitness goals and current progress

Configuration

Environment Variable	Default	Description
GARMIN_TOKEN_STORE	~/.garminconnect	Directory where OAuth tokens are stored
GARMIN_EXPORT_DIR	~/garmin-exports	Directory for downloaded activity files

Development

Testing with MCP Inspector

uv run mcp dev src/garmin_mcp/server.py

This opens a web UI where you can invoke tools individually and inspect responses.

Project Structure

src/garmin_mcp/
├── server.py            # FastMCP server entry point
├── auth.py              # OAuth token management + garmin-mcp-setup CLI
└── tools/
    ├── health.py        # Daily health metrics
    ├── activities.py    # Workout listing and details
    ├── body.py          # Weight, body composition, hydration
    ├── fitness.py       # Training metrics, HRV, race predictions
    ├── devices.py       # Devices, steps, records, SpO2, goals
    └── export.py        # Activity file downloads

Important Notes

• Unofficial API -- This uses undocumented Garmin Connect endpoints via python-garminconnect. Endpoints may change without warning.
• Rate Limits -- Garmin enforces rate limits. Avoid rapid-fire requests; the AI assistant handles this gracefully with error messages.
• Token Refresh -- The underlying garth library handles token refresh automatically. Tokens typically last ~1 year.
• STDIO Safety -- The server never writes to stdout (which would corrupt the MCP transport). All logging goes to stderr.
• No Interactive Auth -- The MCP server only uses pre-saved tokens. Run garmin-mcp-setup separately to authenticate.

License

MIT