mcp-fitbod

Содержание

Обзор  ·  Установка  ·  Конфигурация  ·  Инструменты  ·  Аутентификация  ·  Примечательные находки  ·  Ограничения  ·  Архитектура  ·  Правовая информация

Related MCP server: WHOOP MCP Server

Обзор

mcp-fitbod помещает аккаунт Fitbod за один stdio MCP-сервер, поэтому любой MCP-клиент может работать с вашими данными тренировок напрямую. Он охватывает десять бэкенд-сервисов, а не одну конечную точку:

Самый полезный компонент — pyserve. Большинство интеграций записывают программы наряду с приложением; этот же вызывает сам генератор и получает полную сессию с выбором упражнений, подходами, повторениями, весами и временем отдыха, а затем фильтрует результат по оборудованию, которое у вас действительно есть, и запрашивает замены для всего, что вы не можете выполнить.

Основные возможности

• Каждый инструмент записи по умолчанию использует dry_run=True и возвращает точную полезную нагрузку, которую отправил бы, не затрагивая аккаунт.

• Офлайн-корпус из примерно 1400 упражнений означает, что поиск по каталогу, фильтрация по залам и сопоставление мышц не требуют сетевых вызовов.

• build_routine проверяет каждое движение по вашему залу до записи и удаляет программу при частичном сбое, чтобы ничего не осталось наполовину созданным.

• Анализ (тоннаж, объём по мышцам, расчётный 1RM, застойные упражнения) живёт в чистых функциях без сетевых зависимостей и покрыт модульными тестами на фикстурах.

• Выпуск токенов, обновление по 401, ограничение частоты запросов, пагинация и повторные попытки при временных сбоях обрабатываются внутри клиента.

Установка

Требуется Python 3.10 или новее.

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

Аутентифицируйтесь один раз. Refresh-токен действует около года, и сохраняется только этот токен.

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

Соберите офлайн-корпус упражнений из собственной установки Fitbod. Извлеките APK, затем укажите сборщику на его каталог res/raw.

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

Опишите свой зал, чтобы инструменты могли отбирать выполнимые упражнения.

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

Проверьте, а затем запустите.

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

Конфигурация

Зарегистрируйте сервер в любом MCP-клиенте через stdio:

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

Учётные данные хранятся в .fitbod-credentials.json, доступном для чтения только владельцу и игнорируемом git. Файл содержит только refresh-токен и ничего больше. Ваш пароль никогда не записывается на диск и не попадает в журналы. Чтобы отозвать доступ, смените пароль.

data/gym-profile.json сопоставляет ваше оборудование с 78 типами оборудования Fitbod, включая точные шаги гантелей и блинов, доступные вам, чтобы предписанные нагрузки можно было действительно собрать. Начните с data/gym-profile.example.json и проверьте, что ваши названия корректно сопоставляются с помощью preview_inventory_mapping.

Инструменты

97 инструментов в двенадцати модулях. Каждый инструмент записи принимает dry_run.

Расчётный 1RM использует формулу Эпли. Разминочные подходы исключаются из подсчёта рабочих подходов и тоннажа. Пустой период возвращает пояснительную note вместо голого нуля.

Доступны три движка: foundational_model, algo_direct_client и algo_llamabod. Результаты пост-фильтруются по вашему залу, а всё невозможное автоматически заменяется через exercise_replacement.

Полный временной ряд доступен для веса, сухой массы, жировой массы, процент жира, BMI, BMR и семи обхватов, с данными из Apple Health или Health Connect.

Каталог: 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

Профиль: 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_ask coach_sessions coach_new_session coach_memories coach_session_stats chat

Аналитика: exercise_analytics exercise_benchmarks workout_achievements

Другие сервисы: service_health subscription_status list_blimps dismiss_blimp strava_connection list_public_gyms public_gym_equipment search_places

Питание: nutrition_targets todays_targets recalculate_targets cut_progress

Обходные пути: raw_get и metros_raw_get, оба только для чтения с проверкой пути.

Аутентификация

Три шага, причём каждый микросервис выпускает собственный короткоживущий токен из одного долгоживущего refresh-токена:

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

Клиент кэширует токены доступа на 23 часа и прозрачно перевыпускает их при 401. Обратите внимание на несогласованность между сервисами: nautilus требует refresh_token в теле, тогда как prism, blimp и metros также принимают его в заголовке.

Требуется User-Agent в форме браузера, поскольку известные бот-агенты, такие как curl/*, отклоняются на периферии до того, как запрос достигнет источника.

Примечательные находки

Поведение, на выяснение которого уходит реальное время, задокументировано, чтобы его не приходилось переоткрывать.

• Сосуществуют два режима сериализации. Атрибуты JSON:API используют snake_case, но встроенные документы используют имя исходного свойства как есть, если явная аннотация не переопределяет его. Внутри individual_sets isWarmup и restTime остаются в camelCase, тогда как _id, _created_at и is_amrap имеют переопределения. Если перепутать эти два режима, все поля молча пропадают.

• Некоторые сопоставления невозможно угадать. workoutConfigId сериализуется как default_workout_config_id, circuitsEnabled — как supersets_enabled, а algorithmCoefficient — как algorithm_coeffecient, с опечаткой в передаваемых данных.

• Записанные подходы не используют идентификатор ресурса. Они ссылаются на упражнения по exercise_external_resource_id, а это другой номер. Жим ногами имеет id=291, но external_resource_id=218.

• POST и PUT расходятся в отношении id. POST workout_data отвергает любой id (data.attributes.id should be type integer_id), тогда как PUT workout_data/{id} требует, чтобы data.id совпадал с путём.

• Связи, а не атрибуты. gym_id и equipment_id читаются, но не записываются. Для создания строки gym_equipment нужны связи JSON:API, а не атрибуты.

• Значения перечислений фиксированы, и порядок важен.

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)

• Причуды генератора. algo_versions обязателен, но каждое поле внутри может быть null. Пустой user_equipment или muscle_usages_from_client возвращает 500. exercise_replacement требует, чтобы тренировка была повторена в current_workout, и каждый id из exercise_ids_to_replace должен в ней присутствовать. Генератор не строго соблюдает user_equipment, поэтому всегда выполняйте пост-фильтрацию.

• Всплески запросов подвергаются проверке. 403 с HTML-телом временный и исчезает примерно через 10–30 секунд. Клиент повторяет запрос, а не показывает его как ошибку аутентификации, хотя на первый взгляд она выглядит именно так.

• Длительность указывается в секундах. duration в записанной тренировке — это не минуты, что легко упустить, пока 65-минутная сессия не отобразится как 3908.

Известные ограничения

Подтверждено на аккаунте с подпиской при всех испробованных формах полезной нагрузки:

API питания нет вообще. Инструменты питания хранят цели локально и выводят их из текущего состава тела.

Архитектура

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

Запросы ограничиваются на стороне клиента до 6 в секунду с всплеском до 10. Это скорее бюджет вежливости, а не обнаруженный потолок: 50 параллельных запросов устойчиво давали около 32 в секунду без 429s и без заголовков ограничения скорости ни в одном ответе. Запас есть, если нужна пропускная способность.

Корпус упражнений индексируется по двойному индексу, поскольку записанные подходы и записи каталога используют разные пространства id. По этой причине существуют и reference.by_id(), и reference.by_external_id().

Документация

Каталог упражнений

build_reference.py собирает data/exercise-reference.json из каталога res/raw извлечённого APK Fitbod: примерно 1 400 упражнений с письменными инструкциями, 78 типов оборудования, сопоставления мышечных групп и таблицы весов оборудования. Этот контент принадлежит Fitbod, поэтому здесь не распространяется. Соберите его из собственной установки.

Юридическая информация

Этот проект использует недокументированный API, и это, скорее всего, нарушение условий обслуживания Fitbod, даже несмотря на то, что он работает только с вашим собственным аккаунтом и не обходит оплату. Он существует для личной совместимости с вашими собственными данными тренировок. Используйте его на своём аккаунте, на свой страх и риск, и не направляйте его на чужие аккаунты.

Шестиугольный знак в баннере — оригинальный рисунок, вдохновлённый визуальным стилем Fitbod, а не их товарный знак; этот проект никак не связан с Fitbod, не одобрен им и не аффилирован с ним.

Лицензия

MIT