Tyme Wear MCP Server

Ein Model Context Protocol-Server, der Claude mit der Tyme Wear-Atemsensorplattform verbindet. Analysieren Sie Ihre Ventilationsdaten, Aktivitäten, Schwellenwerte und Trainingszonen direkt über Claude.

Basierend auf derselben Architektur wie trainingpeaks-mcp.

Was ist Tyme Wear?

Tyme Wear stellt den VitalPro-Brustgurt her, einen tragbaren Atemsensor, der Ventilationsmetriken (Atemfrequenz, Atemzugvolumen, Minutenventilation) zusammen mit der Herzfrequenz misst. Es verwendet Ventilationsschwellen (VT1, VT2) zur Definition personalisierter Trainingszonen. Wird von Team Visma | Lease a Bike verwendet.

Related MCP server: Strava MCP Server

Funktionen

• 40 MCP-Tools für Profil, Aktivitäten, Atemdaten, VE-Schwellen, kompakte Aktivitätsanalyse pro Aktivität, Aktivitätsdateien/Erkennung, Trainingspläne, Workout-Empfehlungen, Integrationen, Abonnement/Konto, Ruhe-/Maximalphysiologie und Exporte

• Sichere Anmeldedatenspeicherung über die System-Keychain (macOS Keychain / Windows-Anmeldeinformationsverwaltung) mit AES-256-GCM-verschlüsselter Datei-Fallback

• Auto-Authentifizierung mit Token-Caching und automatischer Neuauthentifizierung bei Ablauf

• Intelligente Atemdaten mit Zusammenfassungs-, Fenster- und Vollmodi zur Vermeidung von Kontextüberlauf

• Aktivitätseinblicke pro Aktivität (tw_get_activity_insights): Erkannte VT1/VT2/VO2max mit gemessener Leistung an der Schwelle, Konfidenzwerte, ein Flag für abgebrochene Tests sowie Zeit/Kalorien pro Zone – in einem Aufruf, ohne FIT-Parsing

• Kompakte Aktivitätsanalyse (tw_get_activity_analysis): Abgeglichene Zeitstempel, beschriftete Zusammenfassungs- und Fähigkeitszustände, pro-Kanal verarbeitet/neu-verarbeitet/FIT-Fallback, deterministische Sekunden-für-Sekunden-Zusammenführung und Paginierung

• Schlanke Aktivitäts-Payloads: tw_get_activity und tw_get_activity_workout_zone_detection lassen standardmäßig mehrere MB große Pro-Sekunde-Arrays weg (Opt-in mit include=[...])

• Öffentlicher Streamable-HTTP-Modus mit Static-Bearer- oder OAuth-Authentifizierung (Ein-Klick-claude.ai-Connector), Single-Tenant auf das Tyme-Wear-Konto des Betreibers

Schnellstart

1. Installation

git clone https://github.com/tkelkermans/tymewear-mcp.git
cd tymewear-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Authentifizierung

tymewear-mcp auth

Geben Sie Ihre Tyme-Wear-E-Mail und Ihr Passwort ein. Die Anmeldedaten werden sicher in Ihrer System-Keychain mit einer verschlüsselten Datei-Fallback gespeichert.

3. Claude Desktop konfigurieren

Fügen Sie zu Ihrer Claude-Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json auf macOS):

{
  "mcpServers": {
    "tymewear": {
      "command": "/path/to/tymewear-mcp/.venv/bin/tymewear-mcp",
      "args": ["serve"]
    }
  }
}

Oder führen Sie tymewear-mcp config aus, um den Code-Snippet mit dem korrekten Pfad zu generieren.

4. Claude Desktop neu starten

Die Tyme-Wear-Tools erscheinen in Claudes Werkzeugliste.

CLI-Befehle

Öffentliche Internet-Bereitstellung

serve-public stellt einen Streamable-HTTP-MCP-Endpunkt für gehostete Bereitstellungen bereit. Er ist authentifiziert und zustandslos; es handelt sich nicht um eine anonyme öffentliche API.

Öffentlicher Server

Setzen Sie die öffentliche URL und ein oder mehrere MCP-Bearer-Tokens über Umgebungsvariablen. Jedes Bearer-Token muss mindestens 32 Zeichen lang sein; verwenden Sie ein generiertes zufälliges Geheimnis.

export TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp"
export TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars"

tymewear-mcp serve-public \
  --host 0.0.0.0 \
  --port 8000 \
  --public-url "$TYMEWEAR_PUBLIC_URL"

Der MCP-Endpunkt ist standardmäßig /mcp. /healthz gibt nur {"status":"ok"} zurück und gibt keine Kundendaten preis.

Container

Das enthaltene Dockerfile führt den öffentlichen Server als Nicht-Root-Benutzer aus. Injizieren Sie Geheimnisse zur Laufzeit:

docker build -t tymewear-mcp-public .

docker run --rm -p 8000:8000 \
  -e TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
  -e TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars" \
  tymewear-mcp-public

Vercel

Das Repository enthält auch einen Vercel-Python-ASGI-Einstiegspunkt auf der obersten Ebene (main.py). Vercels Python-Framework leitet Anfragen direkt an die ASGI-App weiter, daher darf vercel.json /mcp, /healthz oder /.well-known/* nicht auf einen internen Funktionspfad umschreiben. Verknüpfen Sie das lokale Verzeichnis mit dem gewünschten Vercel-Projekt, verbinden Sie dieses Projekt mit dem Git-Repository und konfigurieren Sie dann mindestens TYMEWEAR_PUBLIC_BEARER_TOKENS sowohl für Production als auch für Preview. Der Einstiegspunkt schlägt fehl, wenn die öffentliche Bearer-Token-Umgebungsvariable fehlt. Verwenden Sie ein separates Preview-Bearer-Token, um den Anmeldedatenbereich einzuschränken. TYMEWEAR_PUBLIC_URL wird für Produktionsaliase empfohlen, aber Preview-Bereitstellungen können es von der Vercel-Bereitstellungs-URL ableiten.

PRODUCTION_TOKEN_FILE=/path/to/generated-production-bearer-token
PREVIEW_TOKEN_FILE=/path/to/generated-preview-bearer-token
chmod 600 "$PRODUCTION_TOKEN_FILE" "$PREVIEW_TOKEN_FILE"
vercel link
vercel git connect
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE"
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS preview --sensitive --yes < "$PREVIEW_TOKEN_FILE"

Halten Sie Tokendateien nur für ihren Besitzer lesbar; der Bereitstellungs-Wrapper lehnt Tokendateien ab, die für die Gruppe oder andere zugänglich sind. Verwenden Sie vercel env update TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE" beim Rotieren eines vorhandenen Tokens. Übergeben Sie Bearer-Tokens nicht über vercel deploy --env, Shell-echo oder andere Befehlsargumente, die in der Shell-Historie oder Prozesslisten landen können.

Derselbe Pfad wird von scripts/deploy_public_vercel.sh für manuelle Wiederherstellungsbereitstellungen verwendet. Es erfordert eine bestehende Vercel-Projektverknüpfung, lädt das Token aus einer Datei hoch, stellt die Produktion bereit und führt scripts/verify_public_endpoint.py gegen die bereitgestellte MCP-URL aus:

scripts/deploy_public_vercel.sh --token-file "$PRODUCTION_TOKEN_FILE"

Setzen Sie PYTHON=/path/to/python, wenn der Verifizierer mit einem bestimmten Interpreter ausgeführt werden soll, z. B. der virtuellen Umgebung des Repositorys.

Automatisierte Bereitstellung (CI/CD)

.github/workflows/deploy.yml führt die gesperrte Testsuite (ruff + mypy + pytest) bei jedem Push und Pull-Request aus. Es enthält keine Vercel-Anmeldedaten und stellt die Anwendung nicht bereit.

Die verknüpfte Vercel-Git-Integration erstellt Preview-Bereitstellungen für Feature-Branches und Pull-Requests und erstellt dann die Produktionsbereitstellung, wenn main aktualisiert wird. Es ist kein VERCEL_TOKEN-GitHub-Actions-Geheimnis erforderlich. Laufzeitvariablen wie TYMEWEAR_PUBLIC_BEARER_TOKENS bleiben im Vercel-Projekt verwaltet und bleiben über Git-Bereitstellungen hinweg erhalten.

claude.ai-Connector (OAuth)

Das statische Bearer-Token funktioniert für Header-fähige Clients (Claude Code: claude mcp add --transport http <url> --header "Authorization: Bearer <token>"). Der Connector von claude.ai authentifiziert sich stattdessen über OAuth. Um das MCP dort hinzuzufügen, fungiert der Server als OAuth-Protected Resource: Er validiert JWT-Zugriffstoken von einem verwalteten Anbieter (z. B. WorkOS AuthKit oder Stytch) und erzwingt eine E-Mail-Allowlist. Er bleibt Single-Tenant – jeder autorisierte Benutzer liest die Daten des Betreibers über serverseitige Anmeldedaten.

Setzen Sie diese (sensiblen) Vercel-Umgebungsvariablen, um es zu aktivieren:

Anbieter-Setup (WorkOS AuthKit-Beispiel): Erstellen Sie eine App, aktivieren Sie Google/E-Mail-Login, aktivieren Sie Dynamic Client Registration, damit sich claude.ai selbst registrieren kann, und kopieren Sie die Issuer-URL in TYMEWEAR_PUBLIC_ISSUER_URL. Fügen Sie dann den Connector in claude.ai hinzu → er entdeckt den Anbieter über /.well-known/oauth-protected-resource des Servers, registriert sich und führt den gehosteten Login durch; nur E-Mails auf der Allowlist werden zugelassen.

Der statische TYMEWEAR_PUBLIC_BEARER_TOKENS-Pfad funktioniert weiterhin parallel zu OAuth (Dual-Modus). Ohne TYMEWEAR_PUBLIC_ISSUER_URL ist OAuth deaktiviert und nur der Bearer-Pfad ist aktiv.

Überprüfung nach der Bereitstellung

Überprüfen Sie nach der Bereitstellung den öffentlichen Endpunkt, ohne Geheimnisse preiszugeben:

TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
python scripts/verify_public_endpoint.py --bearer-token-file "$TOKEN_FILE"

Der Verifizierer prüft /healthz, die Ablehnung von nicht authentifiziertem /mcp, authentifiziertes MCP initialize, authentifiziertes tools/list, erforderliche kompakte Analyse-/Profil-Tools sowie öffentliche Sicherheits-/No-Cache-Header. Er bestätigt auch, dass öffentliche Bereitstellungen keine rohen Aktivitätslesevorgänge oder Datenträgerexporte anbieten und dass Standardbereitstellungen keine Mutationstools anbieten.

Öffentliche Client-Authentifizierung

Der öffentliche Modus ist Single-Tenant: Er authentifiziert sich upstream bei Tyme Wear mit den eigenen Anmeldedaten des Betreibers aus TYMEWEAR_EMAIL / TYMEWEAR_PASSWORD (serverseitige Umgebungsvariable), sodass jeder autorisierte Aufrufer die Daten des Betreibers liest. Clients müssen nur nachweisen, dass sie eine Verbindung herstellen dürfen – es gibt kein Pro-Anfrage-Tyme-Wear-Token.

Header-fähige Clients (z. B. Claude Code) senden das statische Gateway-Bearer-Token:

Authorization: Bearer <TYMEWEAR_PUBLIC_BEARER_TOKENS entry>

Wenn OAuth aktiviert ist (TYMEWEAR_PUBLIC_ISSUER_URL gesetzt), senden Clients wie der claude.ai-Connector stattdessen ein vom Anbieter ausgestelltes JWT, das über den gehosteten Login bezogen wurde; der Server validiert es (Signatur über JWKS, Issuer, optionales Audience) und lässt nur E-Mails auf der Allowlist zu. Beide Pfade funktionieren gleichzeitig (Dual-Modus).

Frühere Revisionen erforderten ein X-Tymewear-Token pro Anfrage. Der Single-Tenant-Modus hat es entfernt – Anmeldedaten sind jetzt serverseitig.

Öffentliche Datenrichtlinie

Im öffentlichen Modus:

• Der Zugriff wird durch das statische Bearer-Token und/oder die OAuth-E-Mail-Allowlist gesteuert; nur Identitäten auf der Allowlist stellen eine Verbindung her.

• Die Tyme-Wear-Anmeldedaten des Betreibers befinden sich nur in serverseitigen Umgebungsvariablen (halten Sie sie in einem Secret Manager). Sie werden direkt aus der Umgebung gelesen – der öffentliche Modus berührt nicht die lokale Keychain oder die verschlüsselte Anmeldedatendatei (diese schreiben unter $HOME, was serverlos schreibgeschützt ist).

• Jedes Tool-Ergebnis und jeder stabile öffentliche Fehler durchläuft eine nicht-mutierende rekursive Datenschutzprojektion vor der JSON-Serialisierung. Sie entfernt Nicht-JSON-Werte, nicht-endliche Zahlen, E-Mails, Benutzer-/Konto-/Profil-UUIDs, Geräteidentifikatoren/Seriennummern, Tokens, signierte/Callback/Download-URLs, S3- oder temporäre Pfade, große rohe Felder und Koordinaten außerhalb des expliziten Analyse-Standortvertrags.

• tw_get_activity_analysis ist die öffentliche kompakte Rohdaten-Schnittstelle. Sie behält beschriftete Verfügbarkeit, Fähigkeit, Kanal, Herkunft, Zusammenfassung und paginierte Beispieldaten. include_location muss das Literal true sein; nur raw_samples.data[*].position_lat/position_long und ihre passenden Kanalmetadaten dürfen dann überleben. Zuhause, generische und nicht zusammenhängende Koordinaten werden immer entfernt.

• Öffentliche Antworten enthalten Cache-Control: no-store, Pragma: no-cache, X-Robots-Tag: noindex, nofollow, HSTS für HTTPS-öffentliche URLs und grundlegende Sicherheitsheader, um unbeabsichtigtes Zwischenspeichern, Indizierung und clientseitiges Durchsickern von Kundendaten zu reduzieren.

• Profil-/Aktivitäts-Mutationstools sind standardmäßig ausgeblendet und geben PUBLIC_MUTATIONS_DISABLED zurück. Aktivieren Sie sie nur mit --allow-mutations oder TYMEWEAR_PUBLIC_ALLOW_MUTATIONS=true für vertrauenswürdige Bereitstellungen.

• CSV-, FIT- und Strap-Datei-Export-Tools geben PUBLIC_EXPORTS_DISABLED zurück, da die lokale Implementierung Dateien auf die Festplatte schreibt.

• tw_get_processed_data, tw_get_new_processed_data, tw_get_activity_logs und tw_get_activity_strap_files sind ausgeblendet und geben PUBLIC_RAW_DATA_DISABLED zurück, selbst wenn Mutationen aktiviert sind. Der lokale Stdio-Modus behält diese Tools. Die kompakte Workout-Zonen-Erkennung bleibt öffentlich.

Öffentliche Tool-Fehler sind stabil und geben keine Upstream-Ausnahmetexte weiter:

Produktionshärtung

• Beenden Sie TLS an der Edge und setzen Sie TYMEWEAR_PUBLIC_URL auf die kanonische HTTPS-MCP-URL.

• Halten Sie den Pfad von TYMEWEAR_PUBLIC_URL mit dem gemounteten MCP-Pfad (standardmäßig /mcp) übereinstimmend. Der öffentliche Modus lehnt URL-Abfragezeichenfolgen, Fragmente und Routen/Pfad-Ungleichheiten beim Start ab.

• Fügen Sie TYMEWEAR_PUBLIC_BEARER_TOKENS aus einem Secret Manager ein, nicht aus der Shell-Historie oder der Versionskontrolle. Token mit weniger als 32 Zeichen werden beim Start abgelehnt.

• Halten Sie öffentliche Bereitstellungen schreibgeschützt, es sei denn, Sie haben eine spezifische Anforderung für vertrauenswürdige Clients für Profil-/Aktivitätsmutationen.

• Bevorzugen Sie einen OAuth- oder identitätsbewussten Proxy vor serve-public für nicht vertrauenswürdige Clients; rotieren Sie statische Bearer-Token regelmäßig.

• Wenn Sie einen OAuth-fähigen Proxy oder Autorisierungsserver verwenden, setzen Sie TYMEWEAR_PUBLIC_ISSUER_URL oder --issuer-url, damit MCP-Clients Metadaten zu geschützten Ressourcen entdecken können.

• Öffentliche HTTP-Anfragekörper sind standardmäßig auf 1 MiB begrenzt, einschließlich chunked/streamed Bodies. Überschreiben Sie mit TYMEWEAR_PUBLIC_MAX_BODY_BYTES oder --max-body-bytes nur, wenn eine vertrauenswürdige Bereitstellung größere JSON-RPC-Anfragen benötigt.

• Halten Sie die Protokollierung von Autorisierungs-Headern, Anfragekörpern und Antwortkörpern am Reverse-Proxy und der Anwendungsplattform deaktiviert.

• Beschränken Sie den ausgehenden Netzwerkverkehr auf Tyme Wear-API-Hosts, sofern Ihre Plattform dies unterstützt.

• Setzen Sie explizite Werte für --allowed-host und --allowed-origin, wenn der öffentliche URL-Host nicht der einzige gültige Host/Origin ist. Der öffentliche Modus lehnt nicht vertrauenswürdige Host-Header über alle Routen hinweg ab, verweigert die Wildcard *-Host/Origin-Konfiguration, erfordert, dass erlaubte Origins exakte http(s)-Origins ohne Pfade sind, und verlangt, dass Nicht-Localhost-Origins HTTPS verwenden.

Verfügbare Tools

Auth & Profil

Aktivitäten

Atmungsdaten

Aktivitätsdateien & Erkennung

Trainingspläne & Workouts

Integrationen & Konto

Schwellenwerte & Zonen

Maximalwerte

Exports

Beispiel-Prompts

Nach der Konfiguration kannst du Claude zum Beispiel Folgendes fragen:

• "Zeige mir meine letzten 10 Radaktivitäten"

• "Analysiere die Atemdaten meiner gestrigen Fahrt – was waren mein durchschnittliches VE und die Zeit in jeder Zone?"

• "Was sind meine aktuellen VT1- und VT2-Schwellenwerte fürs Radfahren?"

• "Rufe die Erkenntnisse meines letzten Schwellentests ab – wie hoch ist meine Leistung bei VT2 und wurde VO2max erreicht?"

• "Exportiere meine letzte Aktivität als FIT-Datei"

• "Vergleiche meine VE-Ziele zwischen Laufen und Radfahren"

• "Zeige meinen aktuellen Trainingsplan und die Workout-Empfehlung"

• "Überprüfe, ob meine letzte Fahrt Gurtdateien, Protokolle oder Ergebnisse der Workout-Zonen-Erkennung enthält"

• "Liste meine verbundenen Integrationen und den Abonnementstatus auf"

Sicherheit

• Anmeldedaten werden im System-Keyring gespeichert (bevorzugt) oder in einer AES-256-GCM-verschlüsselten Datei mit PBKDF2-Schlüsselableitung (600.000 Iterationen, maschinenspezifisches Salt)

• Tokens und Anmeldedaten werden niemals in MCP-Tool-Ergebnissen zurückgegeben (vor Erreichen von Claude bereinigt)

• Umgebungsvariablen-Authentifizierung für CI/Container verfügbar: TYMEWEAR_EMAIL + TYMEWEAR_PASSWORD

• Dateiberechtigungen auf 600 (nur Besitzer Lese-/Schreibzugriff) für verschlüsselte Anmeldedatendateien gesetzt

• Der öffentliche Modus erfordert Bearer- oder OAuth-Authentifizierung und ist Single-Tenant: Die vorgelagerte Tyme-Wear-Authentifizierung verwendet serverseitige TYMEWEAR_EMAIL/TYMEWEAR_PASSWORD-Umgebungsvariablen (niemals den lokalen Keyring oder die verschlüsselte Datei, die auf serverloser Umgebung schreibgeschützt sind), jedes Ergebnis wird datenschutzgerecht projiziert, und Rohdaten-/Datei-/Export-Tools sind deaktiviert

Architektur

tymewear-mcp/
├── src/tymewear_mcp/
│   ├── cli.py              # CLI entry point
│   ├── server.py           # MCP server + 40 tool registrations
│   ├── public.py           # Public Streamable HTTP server + bearer/OAuth auth
│   ├── auth/               # Credential storage (keyring → encrypted → env) + OIDC verifier (oidc.py)
│   ├── client/             # Async HTTP client + Pydantic models
│   └── tools/              # Tool implementations (incl. threshold_analysis.py, _slimming.py)
└── tests/                  # 340 tests

Technologie-Stack: Python 3.10+, MCP SDK, httpx, Pydantic, keyring, cryptography, PyJWT

Entwicklung

pip install -e ".[dev]"
pytest tests/ -v          # Run tests
ruff check src tests      # Lint
mypy src/                 # Type check

Lizenz

MIT