Garmin MCP Server

Ein MCP-Server, der deine Garmin Connect-Gesundheits- und Laufdaten als Tools bereitstellt – damit ein LLM wie DeepSeek deine Uhrdaten täglich analysieren und dich wie ein Lauf-/Gesundheitscoach coachen kann, der sich an deinen tatsächlichen Zahlen orientiert.

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, ...)

Funktionen

• Täglicher Gesundheitsüberblick – ein Aufruf liefert Schlaf (Dauer/Score/Phasen), Ruhepuls, HRV (letzte Nacht + Woche), Body Battery, Stress, SpO2, Atemfrequenz, Schritte, Kalorien, Intensitätsminuten, morgendliche Trainingsbereitschaft und Workouts des Tages.

• Lauf-Coaching-Daten – get_run_analysis aggregiert Umfang, gewichtetes Tempo, Herzfrequenz, Kadenz, Höhenmeter, Trainingsbelastung und Wochenentwicklung über einen Datumsbereich; get_activity_detail dringt in die Splits pro Runde vor.

• 18 Tools – für tägliche Kennzahlen, Seriendaten, Aktivitäten, Trainingsstatus/-bereitschaft, VO2max, Rennprognosen, Laktatschwelle, Herzfrequenzzonen, Körperzusammensetzung, persönliche Rekorde und Profil.

• Tokenbasierte Authentifizierung – einmalige Anmeldung (MFA-fähig) und Sitzung wird auf der Festplatte gespeichert; der Server wird automatisch fortgesetzt, keine Passwortabfragen.

• Mock-Modus – GARMIN_MOCK=true liefert deterministische synthetische Daten, damit du die gesamte Pipeline testen kannst, bevor du ein echtes Konto verbindest.

• Built-in DeepSeek bridge – scripts/deepseek_chat.py gibt DeepSeek die Werkzeuge direkt (funktionsaufruf) – interaktiv oder one-shot für Cron.

Related MCP server: Garmin Workouts MCP Server

Anforderungen

• Python 3.10+ (entwicklung auf 3.13)

• Ein Garmin Connect-Konto (kostenlos). Konten mit Zwei-Faktor-Authentifizierung werden unterstützt.

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

Einmalig anmelden (interaktiv, verarbeitet MFA)

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

Dieses forcaut den bei Garmin Connect an, frägt bei Zwei-Faktor-Konten nach dem Einmal-Code (MFA), speichert die OAuth-Tokens unter ~hap/garminconnect (nur für den Besitizer lebbar) und ziet einige echte Datenpunkte, um den/funktonsfähigkeit zu bestätigen. Danach bacht der Server kein Passwort mehr.

Fehlerbehebung Anmelden: Garmin scheist manchmal eine Bot-/Captcha-Upgabe. Lösung: Einmal bei connect.garmin.com im Communicator melden, dann das Startskript nocheinmal ausführen. Wenn du einge schränkt wirst (429), warte eine few Minuten, dann alte den Vorgang neu zu versuchen.

Testen ohne echtes Konto (Mock-Modus)

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

Startet den Server über stdio und übt mit einem MCP-Client jedes Werkzeug – 19 Prüfungen, alle distincts bestanden mit synt hetischen Daten.

Verbindung zu einem MCP-Client

Verweiene deinen Client auf das Startskript ./garmin-mcp-server (der findet die virtuelle Env und PYTHONPATH automatisch):

Claude Desktop – füge in claude_desktop_config.json ein (oder nimm das Beispiel in config/claude_desktop_config.example.json):

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

Beide wichtige: “Cherry Studio”:

Cherry Studio (DeepSeek-freundliche Desktop-Chat): Settings → MCP-Server → Hinzufügen: Name garmin, Typ stdio, Befehl /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server, und wähle den DeepSee–Provider als Modell. AnMeldedaten kompt aus der .env des Projekts, es sind keine Environment- Variablesn im Client nötig.

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

MCP Inspector (Debugg): npx @modelcontextprotocol/inspector und beziehe sie auf das obige Befehl – oder den Server über HTTP starten:

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

DeepSeek Direkt verbinden (optionale Brücke)

DeepSeek's chat API spricht "OpenAI-Stil Function-Caling"-Sprache, daher gibt es hier eine eingehende Brücke, die den Garmin-Server startet, DeepSeek bringtSeek die Tools bei und über lasseneSeek, was abfrragt wird:

.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?"

Schreibe deine eigene Coach-Persona in prompts/coach.md und übergib mit --system-prompt prompts/coach.md (dies ist die Standardeinstellung). Ein Startprompt ist enthalten.

Beacht: Die Web-/Chat-App von DeepSeek unterstützt selbst kein MCP; die obige Brücke ist der Weg zu hilfe, um DeepSeek zu Mail? eben. Jeder Client mit MCP (Claude Desktop, Cherry Studio, Cursor, Oracle Code) funktioniert auch mit deinem eigenen DeepSeek-API-Schlüssel.

Web‑App (Dashboard + Chat)

Ein Frontend für den Browser wird mitgeliefert – kein Client nötig:

.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

Es zeigt:

• Heute-Karten – Schlafensscore/dauer, HRV, Body-Battery, Ruhepuls, Stress, Schrittvs. Ziel, Trainingsbereitschaft, Workouts.

• Diagramme (letzte 7/14/28 Tage) – Ruhepuls und HRV, Herzfrequenzvariabilität, Body-Battery, Stress, nach Woche, wöchentlich gelaufene Distanzen.

• Tabelle der letzten Läufe – Distanz, Tempo, Herzfrequenz, Frequenz, Höhenmeter, Trainingseffekt, Belastung.

• Coach-Chat-Bereich – Fragen in natürlicher Sprache; DeepSeek antwortet mit deinen Live-Garmin-Daten (füge DEEPSEEK_API_KEY hinzu). Dashboards für .env – ohne Funktion, ohne.

Die Web-App hält für die gesamte Dauer eine MCP-Sitzung mit dem Garmin-Server geöffnet, sodass es dieselben Tools und dieselbe Authentifizierung wiederverwendet wie jeder andere Client. Die Diagramme nutzen das Chart.js CDN, der Browser benötigt dazu Internetverbindung.

Verfügbare Tools

Alle Ausgaben sind JSON-Strings; bei Erfolg {"ok": true, ...}, bei Fehler {"ok": false, "error": ...}. Daten Datum format: YYYY-MM-DD (lokale Zeit).

Projektaufbau

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)

Notizen & Hinweise

• Verwendet Garmins unofizielle (Web-/Geräte-)Endpunkte über die Community garminconnect Bibliothek. Garmin kann diese jederzeit ändern; die Formatierer sind defensiv geschrieben, sodass fehlende Felder graceful fallback liefern.

• Token-Datei enthalten langlaufierte Refresh-Tokens – sie geheim halten (~/.garminconnect, geschrieben mit 0600).

• Der Server cached Antworten für GARMIN_CACETTL Sekunden (Standard 600), um Garmin nicht zu überlasten, wenn der LLM Fragen überlappen.

• Das Web-Dashboard-Diagramm lädt Chart.js von einem CDN – der Browser braucht für Diagramme Internet (Karten und Tabelle funktionieren offline weiter).

• Nicht verbunden mit Garmin. Für den privaten Gebrauch.

Lizenz

MIT