mcp-fitbod

Inhalt

Überblick  ·  Installation  ·  Konfiguration  ·  Tools  ·  Authentifizierung  ·  Bemerkenswerte Erkenntnisse  ·  Einschränkungen  ·  Architektur  ·  Rechtliches

Related MCP server: WHOOP MCP Server

Überblick

mcp-fitbod stellt ein Fitbod-Konto hinter einen einzigen stdio-MCP-Server, sodass jeder MCP- Client direkt mit deinen Trainingsdaten arbeiten kann. Es umfasst zehn Backend-Dienste statt eines einzelnen Endpunkts:

Das nützlichste Stück ist pyserve. Die meisten Integrationen schreiben Routinen neben der App; dieses ruft den Generator selbst auf und erhält eine vollständige Sitzung mit Übungsauswahl, Sätzen, Wiederholungen, Gewichten und Pausenzeiten zurück, filtert das Ergebnis gegen die Ausrüstung, die du tatsächlich besitzt, und fordert Ersatz für alles an, was du nicht ausführen kannst.

Highlights

• Jedes Schreib-Tool verwendet standardmäßig dry_run=True und gibt das genaue Payload zurück, das es senden würde, ohne das Konto zu verändern.

• Ein Offline-Korpus von rund 1.400 Übungen bedeutet, dass Katalogabfragen, Fitnessstudio- Filterung und Muskelzuordnung keine Netzwerkaufrufe kosten.

• build_routine validiert jede Bewegung vor dem Schreiben gegen dein Fitnessstudio und löscht die Routine bei teilweisem Fehlschlag, sodass nichts halb erstellt zurückbleibt.

• Analysen (Tonnage, Volumen pro Muskel, geschätztes 1RM, stagnierende Übungen) leben in reinen Funktionen ohne Netzwerkabhängigkeit und werden mit Fixtures unit-getestet.

• Token-Minting, Aktualisierung bei 401, Rate-Limiting, Paginierung und erneute Versuche bei vorübergehenden Herausforderungen werden alle innerhalb des Clients behandelt.

Installation

Erfordert Python 3.10 oder neuer.

git clone https://github.com/Muno459/mcp-fitbod
cd mcp-fitbod
pip install -e ".[dev]"

Authentifiziere dich einmal. Das Refresh-Token hält etwa ein Jahr, und nur dieses Token wird gespeichert.

FITBOD_EMAIL='you@example.com' FITBOD_PASSWORD='...' python -m fitbod.auth

Erstelle den Offline-Übungskorpus aus deiner eigenen Fitbod-Installation. Extrahiere die APK und richte dann den Builder auf deren res/raw-Verzeichnis.

python build_reference.py --apk-res /path/to/fitbod/res/raw

Beschreibe dein Fitnessstudio, damit Tools auf ausführbare Übungen filtern können.

cp data/gym-profile.example.json data/gym-profile.json
$EDITOR data/gym-profile.json

Überprüfe und führe dann aus.

python -m pytest tests/ -q     # offline: parsing and analysis
python smoke_test.py           # live: every tool, writes are dry-run
python server.py

Konfiguration

Registriere den Server bei einem beliebigen MCP-Client über stdio:

{
  "mcpServers": {
    "fitbod": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-fitbod/server.py"]
    }
  }
}

Die Credentials liegen in .fitbod-credentials.json, nur für den Besitzer lesbar und gitignored. Die Datei enthält das Refresh-Token und sonst nichts. Dein Passwort wird nie auf die Festplatte geschrieben und nie protokolliert. Um den Zugriff zu widerrufen, ändere dein Passwort.

data/gym-profile.json bildet die Ausrüstung, die du besitzt, auf die 78 Ausrüstungstypen von Fitbod ab, einschließlich der genauen Kurzhantel- und Scheibenabstufungen, die dir zur Verfügung stehen, sodass vorgegebene Lasten solche sind, die du tatsächlich zusammenstellen kannst. Beginne mit data/gym-profile.example.json und prüfe, ob deine Namen mit preview_inventory_mapping aufgelöst werden.

Tools

97 Tools in zwölf Modulen. Jedes Schreib-Tool akzeptiert dry_run.

Geschätztes 1RM verwendet Epley. Aufwärmsätze sind von den Arbeitssatz-Zählungen und der Tonnage ausgeschlossen. Ein leeres Zeitfenster gibt einen erklärenden note zurück, statt einer bloßen Null.

Drei Engines sind wählbar: foundational_model, algo_direct_client und algo_llamabod. Die Ergebnisse werden gegen dein Fitnessstudio nachgefiltert, und alles Unmögliche wird automatisch über exercise_replacement ausgetauscht.

Eine vollständige Zeitreihe ist verfügbar für Gewicht, Magermasse, Fettmasse, Körperfett, BMI, BMR und sieben Umfänge, bezogen aus Apple Health oder Health Connect.

Katalog: find_exercises exercise_detail search_exercises_live exercise_details_live list_equipment muscle_groups warm_start_lookup onboarding_one_rep_maxes seed_one_rep_max api_surface gym_profile

Profil: get_profile update_profile add_injury list_injuries delete_injury rate_exercise list_exercise_ratings registered_devices app_config selected_cardio add_selected_cardio remove_selected_cardio selected_resistance_bands

Coach und Chat: coach_ask coach_sessions coach_new_session coach_memories coach_session_stats chat

Analysen: exercise_analytics exercise_benchmarks workout_achievements

Weitere Dienste: service_health subscription_status list_blimps dismiss_blimp strava_connection list_public_gyms public_gym_equipment search_places

Ernährung: nutrition_targets todays_targets recalculate_targets cut_progress

Notausstiege: raw_get und metros_raw_get, beide schreibgeschützt mit Pfadvalidierung.

Authentifizierung

Drei Schritte, wobei jeder Microservice sein eigenes kurzlebiges Token aus einem langlebigen Refresh-Token prägt:

POST gate-keeper.fitbod.me/users/login   {"user":{"email","password"}}
  -> 201, refresh JWT in the Authorization RESPONSE header, exp about 1 year

POST <service>.fitbod.me/access_token    {"refresh_token":"<raw jwt>"}
  -> 201 {"access_token": ...}, aud=<service>.prod.fitbod.me, about 24h

Authorization: Bearer <access_token>  ->  https://<service>.fitbod.me/...

Der Client cached Zugriffstokens für 23 Stunden und prägt sie bei einem 401 transparent neu. Beachte die Inkonsistenz zwischen den Diensten: nautilus verlangt refresh_token im Body, während prism, blimp und metros es auch als Header akzeptieren.

Ein browserähnlicher User-Agent ist erforderlich, da bekannte Bot-Agenten wie curl/* am Edge abgewiesen werden, bevor die Anfrage den Origin erreicht.

Bemerkenswerte Erkenntnisse

Verhalten, dessen Ermittlung echte Zeit kostet, hier dokumentiert, damit es nicht erneut entdeckt werden muss.

Zwei Serialisierungsregime koexistieren. JSON:API-Attribute sind snake_case, aber eingebettete Dokumente verwenden den Quell-Eigenschaftsnamen wörtlich, sofern keine explizite Annotation ihn überschreibt. Innerhalb von individual_sets bleiben isWarmup und restTime camelCase, während _id, _created_at und is_amrap Überschreibungen tragen. Wer die beiden verwechselt, verliert stillschweigend jedes Feld.

Manche Zuordnungen sind nicht zu erraten. workoutConfigId serialisiert als default_workout_config_id, circuitsEnabled als supersets_enabled, und algorithmCoefficient als algorithm_coeffecient – auf dem Draht falsch geschrieben.

Protokollierte Sätze verwenden nicht die Ressourcen-ID. Sie referenzieren Übungen über exercise_external_resource_id, was eine andere Nummer ist. Leg Press hat id=291, aber external_resource_id=218.

POST und PUT sind sich bei IDs uneinig. POST workout_data lehnt jede id ab (data.attributes.id should be type integer_id), während PUT workout_data/{id} verlangt, dass data.id mit dem Pfad übereinstimmt.

Beziehungen versus Attribute. gym_id und equipment_id sind lesbar, aber nicht schreibbar. Das Erstellen einer gym_equipment-Zeile erfordert JSON:API-Beziehungen, keine Attribute.

Enum-Werte sind festgelegt und die Reihenfolge ist entscheidend.

FitnessGoal          0 GENERAL_FITNESS  1 STRENGTH_TRAINING  2 MUSCLE_TONE
                     3 BODYBUILDING     4 POWERLIFTING       5 OLYMPICWEIGHTLIFTING
MuscleSplit          0 FRESH_MUSCLE_GROUPS  1 UPPER_LOWER  2 FULL_BODY  3 PPL
ExperienceLevel      0 BEGINNER  1 INTERMEDIATE  2 EXPERT
WorkoutVariability   1 MORE_CONSISTENCY  3 SUGGESTED  5 MORE_VARIABILITY
StrengthAggregate    push, pull, lower   (there is no upper and no core)
ExerciseRating       like, dislike, exclude   (lowercase; uppercase returns 500)

Generator-Eigenheiten. algo_versions ist erforderlich, aber jedes Feld darin darf null sein. Ein leeres user_equipment oder muscle_usages_from_client liefert eine 500. exercise_replacement benötigt das Training als current_workout zurückgespiegelt, und jede ID in exercise_ids_to_replace muss darin vorkommen. Der Generator beachtet user_equipment nicht strikt, also filtere immer nach.

Bursts werden mit einer Challenge beantwortet. Ein 403 mit einem HTML-Body ist vorübergehend und verschwindet in etwa 10 bis 30 Sekunden. Der Client wiederholt die Anfrage, anstatt sie als Auth-Fehler anzuzeigen, was sie auf den ersten Blick zu sein scheint.

Dauern sind Sekunden. duration bei einem protokollierten Training ist nicht in Minuten, was leicht zu übersehen ist, bis eine 65-minütige Einheit als 3908 angezeigt wird.

Bekannte Einschränkungen

Bestätigt gegen ein abonniertes Konto, wobei jede Payload-Form ausprobiert wurde:

Es gibt überhaupt keine Ernährungs-API. Die Ernährungstools speichern Ziele lokal und leiten sie aus der aktuellen Körperzusammensetzung ab.

Architektur

server.py                thin entrypoint, registers tool modules
fitbod/
  client.py              auth chain, rate limiting, retry, pagination
  auth.py                python -m fitbod.auth
  schemas.py             dataclass parsers for both serialisation regimes
  analysis.py            volume, stalled lifts, 1RM. Pure, network free
  reference.py           offline corpus, dual id index, gym filtering
  tools/                 read, catalogue, gym, config, program, profile,
                         metrics, generate, services, coach, extras, nutrition
tests/                   offline tests over recorded fixtures
docs/
  API-MAP.md             145 endpoints, 365 request and response models
  SCHEMAS.md             field level schemas with exact wire names
build_reference.py       builds the offline corpus from an extracted APK
smoke_test.py            exercises all 97 tools live, writes dry-run by default

Anfragen werden clientseitig auf 6 pro Sekunde mit einem Burst von 10 begrenzt. Das ist ein Höflichkeitsbudget und keine entdeckte Obergrenze: 50 gleichzeitige Anfragen erreichten etwa 32 pro Sekunde, ohne 429s und ohne Rate-Limit-Header in irgendeiner Antwort. Es gibt Spielraum, falls du Durchsatz benötigst.

Der Übungskorpus wird über einen dualen Index erschlossen, da protokollierte Sätze und Katalogeinträge unterschiedliche ID-Räume verwenden. reference.by_id() und reference.by_external_id() existieren beide aus diesem Grund.

Dokumentation

Der Übungskatalog

build_reference.py erstellt data/exercise-reference.json aus dem Verzeichnis res/raw einer extrahierten Fitbod-APK: ungefähr 1.400 Übungen mit schriftlichen Anleitungen, 78 Gerätetypen, Muskelgruppen-Zuordnungen und Gerätegewicht-Tabellen. Dieser Inhalt gehört Fitbod und wird daher hier nicht verteilt. Erstelle ihn aus deiner eigenen Installation.

Rechtliches

Dieses Projekt verwendet eine undokumentierte API und verstößt sehr wahrscheinlich gegen Fitbods Nutzungsbedingungen, auch wenn es nur dein eigenes Konto betrifft und keine Zahlungen umgeht. Es dient der persönlichen Interoperabilität mit deinen eigenen Trainingsdaten. Verwende es auf deinem eigenen Konto, auf eigenes Risiko, und richte es nicht auf die Konten anderer.

Das Sechseck-Symbol im Banner ist eine originelle Zeichnung, inspiriert von Fitbods visueller Identität, nicht deren Markenzeichen. Dieses Projekt ist in keiner Weise mit Fitbod verbunden, wird von Fitbod nicht unterstützt und steht in keiner Verbindung zu Fitbod.

Lizenz

MIT