mcp-fitbod

Contenido

Descripción general · Instalación · Configuración · Herramientas · Autenticación · Hallazgos notables · Limitaciones · Arquitectura · Legal

Related MCP server: WHOOP MCP Server

Descripción general

mcp-fitbod sitúa una cuenta de Fitbod detrás de un único servidor MCP stdio, de modo que cualquier cliente MCP pueda trabajar directamente con tus datos de entrenamiento. Abarca diez servicios backend en lugar de un único endpoint:

La pieza más útil es pyserve. La mayoría de las integraciones escriben rutinas junto a la aplicación; esta llama al propio generador y recibe una sesión completa con selección de ejercicios, series, repeticiones, cargas y tiempos de descanso, y luego filtra el resultado según el equipamiento que realmente tienes y solicita reemplazos para cualquier cosa que no puedas realizar.

Aspectos destacados

• Toda herramienta de escritura usa dry_run=True por defecto y devuelve la carga útil exacta que enviaría, sin tocar la cuenta.

• Un corpus offline de aproximadamente 1.400 ejercicios hace que las búsquedas en el catálogo, el filtrado por gimnasio y el mapeo muscular no requieran llamadas de red.

• build_routine valida cada movimiento contra tu gimnasio antes de escribir, y elimina la rutina si falla parcialmente para que nada quede a medio crear.

• El análisis (tonelaje, volumen por músculo, 1RM estimado, levantamientos estancados) vive en funciones puras sin dependencia de red, probadas unitariamente con datos de prueba.

• La acuñación de tokens, la renovación en 401, la limitación de velocidad, la paginación y los reintentos ante desafíos transitorios se manejan dentro del cliente.

Instalación

Requiere Python 3.10 o superior.

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

Autentícate una vez. El token de actualización dura aproximadamente un año, y solo ese token se persiste.

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

Construye el corpus de ejercicios offline desde tu propia instalación de Fitbod. Extrae el APK y apunta el constructor a su directorio res/raw.

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

Describe tu gimnasio para que las herramientas puedan filtrar los ejercicios realizables.

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

Verifica y luego ejecuta.

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

Configuración

Registra el servidor con cualquier cliente MCP a través de stdio:

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

Las credenciales viven en .fitbod-credentials.json, legible por el propietario e ignorado por git. El archivo contiene el token de actualización y nada más. Tu contraseña nunca se escribe en disco ni se registra. Para revocar el acceso, cambia tu contraseña.

data/gym-profile.json mapea el equipamiento que tienes sobre los 78 tipos de equipamiento de Fitbod, incluidos los incrementos exactos de mancuernas y discos disponibles para ti, de modo que las cargas prescritas sean las que realmente puedes montar. Comienza con data/gym-profile.example.json y comprueba que tus nombres se resuelven con preview_inventory_mapping.

Herramientas

97 herramientas repartidas en doce módulos. Toda herramienta de escritura acepta dry_run.

El 1RM estimado usa la fórmula de Epley. Las series de calentamiento se excluyen de los recuentos de series de trabajo y del tonelaje. Una ventana vacía devuelve una note explicativa en lugar de un cero escueto.

Se pueden seleccionar tres motores: foundational_model, algo_direct_client y algo_llamabod. Los resultados se filtran posteriormente contra tu gimnasio, y cualquier cosa imposible se intercambia automáticamente mediante exercise_replacement.

Hay una serie temporal completa disponible para peso, masa magra, masa grasa, grasa corporal, IMC, TMB y siete circunferencias, con datos de Apple Health o Health Connect.

Catálogo: 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

Perfil: 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 y chat: coach_ask coach_sessions coach_new_session coach_memories coach_session_stats chat

Analíticas: exercise_analytics exercise_benchmarks workout_achievements

Otros servicios: service_health subscription_status list_blimps dismiss_blimp strava_connection list_public_gyms public_gym_equipment search_places

Nutrición: nutrition_targets todays_targets recalculate_targets cut_progress

Vías de escape: raw_get y metros_raw_get, ambas de solo lectura con validación de ruta.

Autenticación

Tres pasos, con cada microservicio acuñando su propio token de corta duración a partir de un único token de actualización de larga duración:

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/...

El cliente almacena en caché los tokens de acceso durante 23 horas y los vuelve a acuñar de forma transparente ante un 401. Nótese la inconsistencia entre servicios: nautilus exige refresh_token en el cuerpo, mientras que prism, blimp y metros también lo aceptan como cabecera.

Se requiere un User-Agent con forma de navegador, ya que los agentes bot conocidos, como curl/*, son rechazados en el borde antes de que la solicitud llegue al origen.

Hallazgos notables

Comportamiento que cuesta tiempo de verdad averiguar, documentado para que no haya que redescubrirlo.

Conviven dos regímenes de serialización. Los atributos JSON:API están en snake_case, pero los documentos incrustados usan el nombre de la propiedad de origen tal cual, salvo que una anotación explícita lo sobrescriba. Dentro de individual_sets, isWarmup y restTime permanecen en camelCase, mientras que _id, _created_at e is_amrap llevan sobrescrituras. Confundir ambos hace que se pierdan silenciosamente todos los campos.

Algunos mapeos son imposibles de adivinar. workoutConfigId se serializa como default_workout_config_id, circuitsEnabled como supersets_enabled, y algorithmCoefficient como algorithm_coeffecient, mal escrito en el cable.

Las series registradas no usan el id del recurso. Hacen referencia a los ejercicios mediante exercise_external_resource_id, que es un número distinto. Leg Press es id=291 pero external_resource_id=218.

POST y PUT discrepan sobre los ids. POST workout_data rechaza cualquier id (data.attributes.id should be type integer_id), mientras que PUT workout_data/{id} exige que data.id coincida con la ruta.

Relaciones frente a atributos. gym_id y equipment_id son legibles pero no escribibles. Crear una fila de gym_equipment requiere relaciones JSON:API, no atributos.

Los valores de los enums son fijos y el orden importa.

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)

Peculiaridades del generador. algo_versions es obligatorio, pero todos sus campos internos pueden ser null. Un user_equipment o muscle_usages_from_client vacío devuelve un 500. exercise_replacement necesita que se le devuelva el entrenamiento como current_workout, y todos los ids de exercise_ids_to_replace deben aparecer en él. El generador no respeta estrictamente user_equipment, así que aplica siempre un post-filtrado.

Las ráfagas se rechazan. Un 403 con cuerpo HTML es transitorio y se resuelve en aproximadamente 10 a 30 segundos. El cliente lo reintenta en lugar de mostrarlo como un error de autenticación, que es lo que parece a primera vista.

Las duraciones se expresan en segundos. duration en un entrenamiento registrado no está en minutos, algo fácil de pasar por alto hasta que una sesión de 65 minutos se lee como 3908.

Limitaciones conocidas

Confirmado contra una cuenta suscrita con todas las formas de payload probadas:

No hay ninguna API de nutrición. Las herramientas de nutrición almacenan los objetivos localmente y los derivan de la composición corporal en vivo.

Arquitectura

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

Las solicitudes se limitan en el cliente a 6 por segundo con una ráfaga de 10. Eso es un presupuesto de cortesía, no un límite descubierto: 50 solicitudes concurrentes sostuvieron unas 32 por segundo sin ningún 429 y sin cabeceras de límite de tasa en ninguna respuesta. Hay margen si necesitas rendimiento.

El corpus de ejercicios se indexa mediante un índice dual, porque las series registradas y las entradas del catálogo usan espacios de ids distintos. reference.by_id() y reference.by_external_id() existen por esa razón.

Documentación

El catálogo de ejercicios

build_reference.py construye data/exercise-reference.json a partir del directorio res/raw de un APK de Fitbod extraído: aproximadamente 1.400 ejercicios con instrucciones escritas, 78 tipos de equipamiento, asignaciones de grupos musculares y tablas de peso del equipamiento. Ese contenido pertenece a Fitbod, por lo que no se distribuye aquí. Constrúyelo desde tu propia instalación.

Aspectos legales

Esto utiliza una API no documentada y muy probablemente infringe los términos de servicio de Fitbod, aunque solo toca tu propia cuenta y no elude el pago. Existe para la interoperabilidad personal con tus propios datos de entrenamiento. Úsalo en tu propia cuenta, bajo tu propio riesgo, y no lo dirijas a la de nadie más.

La marca hexagonal del banner es un dibujo original inspirado en la identidad visual de Fitbod, no su marca registrada, y este proyecto no está afiliado, respaldado ni conectado con Fitbod de ninguna manera.

Licencia

MIT