Garmin Connect MCP Server
A Model Context Protocol (MCP) server that exposes your Garmin Connect health and fitness data to AI assistants. Ask your AI about your sleep, heart rate, workouts, stress, body battery, and more.
Features
- 34 tools covering health metrics, activities, trends, and comparisons
- Streamable HTTP transport — works with any MCP-compatible client
- Docker-ready — one command to build and run
- Token persistence — authenticate once with Garmin, tokens last ~1 year
- MFA support — handles SMS two-factor authentication
- Parallel data fetching — weekly reports pull 7+ days of data concurrently
- Imperial units — distances converted to miles automatically
Quick Start
Option 1: Docker (Recommended)
# 1. Authenticate with Garmin (one-time)
pip install 'garminconnect>=0.2.20,<0.3'
python garmin_auth.py
# If you hit a 429 from Cloudflare, use the browser-assisted fallback instead:
# python garmin_browser_auth.py
# (see "Browser-assisted login" under Authentication below)
# 2. Build and run
docker compose up -d
# Server is now at http://localhost:8000/mcp
Option 2: Run Directly
# Install dependencies
pip install -r requirements.txt
# Authenticate (if you haven't already)
python garmin_auth.py
# Run the server
python garmin_mcp_server.py
# Or with FastMCP CLI:
fastmcp run garmin_mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000
Authentication
Garmin Connect uses OAuth tokens stored in ~/.garminconnect/. Run the auth script once:
python garmin_auth.py
This will:
- Prompt for your Garmin email and password
- Handle MFA if enabled (SMS code)
- Save OAuth tokens to
~/.garminconnect/
Tokens last approximately one year. If they expire, just run garmin_auth.py again.
You can also set environment variables for non-interactive auth:
export GARMIN_EMAIL="[email protected]"
export GARMIN_PASSWORD="your-password"
Note on
garminconnectversion:requirements.txtpins to<0.3. The 0.3.x release rewrote the login flow with new strategies that Cloudflare currently 429s, and it also removed theclient.garthattribute this repo relies on. Stay on0.2.xuntil the upstream situation settles.
Browser-assisted login (Cloudflare fallback)
If garmin_auth.py fails with 429 Too Many Requests from sso.garmin.com, Garmin's Cloudflare is blocking the scripted login POST from your IP. Use the browser-assisted fallback instead:
python garmin_browser_auth.py
This script:
- Opens Garmin's SSO sign-in page in your real browser (which Cloudflare allows)
- You sign in normally — MFA works natively because the browser handles it
- You paste the post-login
ticket=ST-...value back into the script - The script exchanges the ticket for OAuth1/OAuth2 tokens via
connectapi.garmin.com(a different host that isn't Cloudflare-walled) and writes the same~/.garminconnect/oauth1_token.jsonandoauth2_token.jsonfiles thatgarmin_auth.pyproduces
No other code needs to change — garmin_mcp_server.py loads the resulting tokens the same way. The most reliable way to grab the ticket is to open Chrome DevTools → Network tab → enable "Preserve log" before clicking Sign In, then inspect the response body of the POST /sso/signin request and copy the ST-... value.
Available Tools (34)
Daily Health
Activities & Training
Body & Composition
Trends & Reports
Device
Client Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"garmin": {
"url": "http://localhost:8000/mcp"
}
}
}
Any MCP Client (Streamable HTTP)
Point your client at:
http://localhost:8000/mcp
The server uses Streamable HTTP transport, which is supported by the MCP SDK and most modern clients.
LiteLLM
Add to your LiteLLM config.yaml:
mcp_servers:
garmin:
url: "http://localhost:8000/mcp"
transport: "streamable-http"
Stdio Transport
If your client only supports stdio, you can run directly:
{
"mcpServers": {
"garmin": {
"command": "python",
"args": ["path/to/garmin_mcp_server.py"]
}
}
}
Example Queries
Once connected, ask your AI things like:
- "How did I sleep last night?"
- "What's my resting heart rate trend this week?"
- "Show me my last 5 strength training sessions with sets and reps"
- "Compare my sleep this week vs last week"
- "What's my body battery at right now?"
- "Give me a full weekly health report"
- "How many steps have I averaged this month?"
Project Structure
├── garmin_mcp_server.py # MCP server (34 tools)
├── garmin_auth.py # One-time Garmin authentication
├── garmin_browser_auth.py # Browser-assisted auth fallback (Cloudflare 429 workaround)
├── run_mcp_server.sh # Server launch script
├── Dockerfile # Container build
├── docker-compose.yml # Docker Compose config
├── requirements.txt # Python dependencies
└── LICENSE # MIT
Environment Variables
Troubleshooting
Authentication failed: Run python garmin_auth.py to re-authenticate. Tokens may have expired.
429 Too Many Requests on login: Garmin's Cloudflare is rate-limiting the scripted login POST to sso.garmin.com/sso/signin. Use python garmin_browser_auth.py instead (see the Browser-assisted login section) — it signs you in via your real browser and then exchanges the SSO ticket against connectapi.garmin.com, which isn't blocked the same way. Also make sure you're on garminconnect<0.3 — the 0.3.x rewrite hits the same wall with every strategy it tries.
AttributeError: 'Garmin' object has no attribute 'garth': You're on garminconnect>=0.3.0, which dropped the garth attribute this repo uses. Downgrade with pip install 'garminconnect>=0.2.20,<0.3'.
Empty data for some metrics: Your Garmin device may not track that metric, or data hasn't synced yet.
Connection refused: Make sure the server is running and port 8000 is accessible. For Docker, check docker compose logs.
Built With
- FastMCP — MCP server framework
- garminconnect — Garmin Connect API client
License
MIT — see LICENSE