Garmin MCP Server

An MCP server that exposes your Garmin Connect health and running data as tools — so an LLM like DeepSeek can analyze your watch data daily and coach you like a running/health coach that adapts to your actual numbers.

Garmin watch ──sync──▶ Garmin Connect ──▶ garmin-mcp (this server)
                                                │  MCP tools (stdio / HTTP)
                                                ▼
                       DeepSeek (via scripts/deepseek_chat.py) or any MCP client
                       (Claude Desktop, Cherry Studio, Cursor, Claude Code, ...)

Features

• Daily health digest — one call returns sleep (duration/score/stages), resting HR, HRV (last night + weekly), body battery, stress, SpO2, respiration, steps, calories, intensity minutes, morning training readiness and any workouts for a day.
• Run coaching data — get_run_analysis aggregates volume, weighted pace, HR, cadence, elevation, training load and weekly trends across a date range; get_activity_detail drills into per-lap splits.
• 18 tools covering daily metrics, series data, activities, training status/readiness, VO2max, race predictions, lactate threshold, HR zones, body composition, personal records and profile.
• Token-based auth — log in once (MFA-capable) and sessions are saved to disk; the server resumes automatically, no password prompts.
• Mock mode — GARMIN_MOCK=true serves deterministic synthetic data so you can test the whole pipeline before connecting a real account.
• Built-in DeepSeek bridge — scripts/deepseek_chat.py gives DeepSeek the tools directly (function calling), interactive or one-shot for cron.

Requirements

• Python 3.10+ (developed on 3.13)
• A Garmin Connect account (free). Two-factor enabled accounts are supported.

Setup

cd /Users/jai/Documents/garmin_mcp_app

# 1. Create the virtualenv and install dependencies
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Configure credentials
cp .env.example .env        # then edit .env: GARMIN_EMAIL, GARMIN_PASSWORD

Log in once (interactive, handles MFA)

.venv/bin/python -m garmin_mcp.login_cli --verify

This authenticates with Garmin Connect, prompts for the one-time MFA code if your account uses two-factor auth, saves the OAuth tokens to ~/.garminconnect (owner-only permissions), and pulls a few real data points to confirm everything works. From then on the server needs no password.

Troubleshooting login: Garmin sometimes throws a bot/captcha challenge. Fix: log into connect.garmin.com once in your browser, then retry the login script. If you get rate-limited (429), wait a few minutes before retrying.

Test without a real account (mock mode)

GARMIN_MOCK=true .venv/bin/python scripts/smoke_test.py

Boots the server over stdio and exercises every tool as a real MCP client — 19 checks, all expected to pass with synthetic data.

Connect to an MCP client

Point your client at the launcher script ./garmin-mcp-server (it resolves the venv and PYTHONPATH automatically):

Claude Desktop — add to claude_desktop_config.json (or use the example in config/claude_desktop_config.example.json):

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/jai/Documents/garmin_mcp_app/garmin-mcp-server",
      "type": "stdio"
    }
  }
}

Cherry Studio (DeepSeek-friendly desktop chat): Settings → MCP Servers → Add: Name garmin, type stdio, command /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server, and select your DeepSeek provider as the model. Credentials come from the project .env, so no env vars are needed in the client.

Claude Code / Cursor / Cline: mcp add garmin -- /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server

MCP Inspector (debugging): npx @modelcontextprotocol/inspector and point it at the command above — or run the server over HTTP:

./garmin-mcp-server --transport streamable-http --port 8000

Connect DeepSeek directly (optional bridge)

DeepSeek's chat API speaks OpenAI-style function calling, so this repo includes a small bridge that starts the Garmin server, hands DeepSeek its tools, and lets it decide what to query:

.venv/bin/pip install -r requirements-deepseek.txt   # adds 'openai'
# add DEEPSEEK_API_KEY to .env (see .env.example)

# interactive coach chat (uses prompts/coach.md as the system prompt)
.venv/bin/python scripts/deepseek_chat.py

# one-shot — cron-friendly ("daily analysis" job)
.venv/bin/python scripts/deepseek_chat.py --once "How was my recovery today? What should today's run be?"

Write your own coaching persona in prompts/coach.md and pass it with --system-prompt prompts/coach.md (it's the default). A starter prompt is included.

Note: the DeepSeek web/chat app doesn't support MCP itself; the bridge above is the way to use DeepSeek with this server. Any MCP-capable client (Claude Desktop, Cherry Studio, Cursor, Claude Code) also works with your own DeepSeek API key.

Web app (dashboard + chat)

A browser front end is included — no MCP client needed:

.venv/bin/pip install -r requirements-web.txt    # fastapi + uvicorn
./garmin-web                                     # http://127.0.0.1:8080
./garmin-web --mock                              # try it with synthetic data
./garmin-web --port 9000                         # different port

It shows:

• Today cards — sleep score/duration, HRV, body battery, resting HR, stress, steps vs goal, training readiness, workouts.
• Charts (last 7/14/28 days) — resting HR + HRV, sleep, body battery, steps, weekly stress, weekly run distance.
• Recent runs table — distance, pace, HR, cadence, elevation, training effect, load.
• Coach chat panel — ask questions in natural language; DeepSeek answers using your live Garmin data (add DEEPSEEK_API_KEY to .env). The dashboard itself works without a key.

The web app keeps one MCP session to the Garmin server open for its whole lifetime, so it reuses the exact same tools and auth as every other client. The charts use the Chart.js CDN, so the browser needs internet access.

Available tools

Tool	Returns
get_health_snapshot(date)	Full daily digest: sleep, HR, HRV, body battery, stress, SpO2, readiness, activities
get_daily_summary(date)	Steps/goal, distance, calories, floors, intensity minutes, HR, stress, SpO2, respiration
get_steps(date) / get_heart_rate(date) / get_stress(date) / get_body_battery(date)	Daily series with hourly averages
get_sleep(date)	Duration, score, qualifier, stage breakdown, sleep SpO2
get_hrv(date)	Last-night avg/min/max, weekly average, status
get_resting_heart_rate(start, end)	Daily RHR series over a range
get_health_series(start, end)	Aligned per-date rows (RHR, body battery, sleep, HRV, steps, runs) + weekly stress — powers the dashboard charts
get_activities(start, end, activity_type?)	Activity list with pace, HR, cadence, TE, VO2max, load
get_activity_detail(activity_id)	Single activity + per-lap splits
get_run_analysis(start, end)	Coach rollup: volume, weighted pace, weekly trends, per-run rows
get_training_status(date) / get_training_readiness(date)	Garmin training load/status, morning readiness + subscores
get_fitness_metrics()	VO2max, race predictions, lactate threshold, HR zones
get_body_composition(start, end)	Weight/BMI/body-fat/muscle/bone/water history
get_personal_records() / get_profile()	PRs and account profile

All outputs are JSON strings; {"ok": true, ...} on success, {"ok": false, "error": ...} on failure. Dates are YYYY-MM-DD (local time).

Project layout

src/garmin_mcp/
  server.py          MCP server (tools, transports, CLI)
  garmin_client.py   real Garmin Connect client (token resume, cache) + mock
  formatters.py      raw Garmin payloads → compact LLM-friendly JSON
  config.py          env / .env settings
  login_cli.py       one-time interactive login (MFA-capable)
  deepseek.py        shared DeepSeek ↔ MCP chat core (CLI + web app)
scripts/
  smoke_test.py      end-to-end MCP client test (mock by default)
  deepseek_chat.py   DeepSeek ↔ MCP bridge (interactive or --once)
  web_app.py         FastAPI backend for the web dashboard + chat
web/                 frontend (index.html, app.js, style.css)
garmin-mcp-server    executable launcher for MCP clients
garmin-web           executable launcher for the web app
config/              Claude Desktop config example
prompts/coach.md     your coach system prompt (edit me)

Notes & caveats

• This uses Garmin's unofficial (web/device) endpoints via the community garminconnect library. Garmin can change these at any time; the formatters are written defensively so missing fields degrade gracefully.
• Token files contain long-lived refresh tokens — keep them private (~/.garminconnect, written 0600).
• The server caches responses for GARMIN_CACHE_TTL seconds (default 600) to avoid hammering Garmin when the LLM asks overlapping questions.
• The web dashboard charts load Chart.js from a CDN — the browser needs internet access for the charts (cards and the table still work offline).
• Not affiliated with Garmin. For personal use.

License

MIT