mcp-fitbod

목차

개요 ·  설치 ·  구성 ·  도구 ·  인증 ·  주요 발견 사항 ·  제한 사항 ·  아키텍처 ·  법적 고지

Related MCP server: WHOOP MCP Server

개요

mcp-fitbod는 Fitbod 계정을 단일 stdio MCP 서버 뒤에 배치하므로 모든 MCP 클라이언트가 트레이닝 데이터를 직접 다룰 수 있습니다. 단일 엔드포인트가 아닌 10개의 백엔드 서비스에 걸쳐 있습니다:

가장 유용한 부분은 pyserve입니다. 대부분의 통합은 앱 과 함께 루틴을 작성합니다. 이 서버는 생성기 자체를 호출하여 운동 선택, 세트, 반복, 중량 및 휴식 시간이 포함된 완전한 세션을 돌려받은 다음, 실제로 보유한 장비를 기준으로 결과를 필터링하고 수행할 수 없는 항목은 대체를 요청합니다.

주요 기능

• 모든 쓰기 도구는 기본적으로 dry_run=True이며 계정에 영향을 주지 않고 보낼 정확한 페이로드를 반환합니다.

• 약 1,400개 운동으로 구성된 오프라인 코퍼스 덕분에 카탈로그 조회, 체육관 필터링, 근육 매핑에 네트워크 호출이 필요 없습니다.

• build_routine은 쓰기 전에 모든 동작을 체육관 기준으로 검증하고, 부분 실패 시 루틴을 삭제하여 절반만 생성된 상태를 남기지 않습니다.

• 분석(토너지, 근육별 볼륨, 추정 1RM, 정체된 운동)은 네트워크 의존성이 없는 순수 함수로 구현되며 픽스처를 대상으로 단위 테스트됩니다.

• 토큰 발급, 401 시 갱신, 속도 제한, 페이지네이션, 일시적 챌린지 재시도는 모두 클라이언트 내부에서 처리됩니다.

설치

Python 3.10 이상이 필요합니다.

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

한 번 인증하세요. 리프레시 토큰은 약 1년간 유효하며, 해당 토큰만 저장됩니다.

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

구성

stdio를 통해 모든 MCP 클라이언트에 서버를 등록하세요:

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

자격 증명은 .fitbod-credentials.json에 저장되며 소유자만 읽을 수 있고 gitignore 처리됩니다. 이 파일에는 리프레시 토큰만 들어 있습니다. 비밀번호는 디스크에 기록되거나 로그에 남지 않습니다. 액세스를 취소하려면 비밀번호를 변경하세요.

data/gym-profile.json은 보유한 장비를 Fitbod의 78개 장비 유형에 매핑하며, 사용 가능한 정확한 덤벨 및 플레이트 증분을 포함하므로 처방된 중량을 실제로 조립할 수 있습니다. data/gym-profile.example.json에서 시작하고 preview_inventory_mapping으로 이름이 올바르게 해석되는지 확인하세요.

도구

12개 모듈에 걸친 97개 도구. 모든 쓰기 도구는 dry_run을 지원합니다.

추정 1RM은 Epley 공식을 사용합니다. 워밍업 세트는 작업 세트 수와 토너지에서 제외됩니다. 빈 기간은 단순한 0 대신 설명적인 note를 반환합니다.

foundational_model, algo_direct_client, algo_llamabod의 세 가지 엔진을 선택할 수 있습니다. 결과는 체육관 기준으로 사후 필터링되며, 불가능한 항목은 exercise_replacement를 통해 자동 교체됩니다.

체중, 제지방량, 체지방량, 체지방률, BMI, BMR 및 7개 둘레 측정값에 대한 전체 시계열을 사용할 수 있으며, 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, 둘 다 경로 검증이 있는 읽기 전용 입니다.

인증

세 단계로, 모든 마이크로서비스가 하나의 장수명 리프레시 토큰에서 자체 단기 토큰을 발급합니다:

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로 직렬화되는데, 이는 와이어 상에서 철자가 틀린 것입니다.

기록된 세트는 리소스 id를 사용하지 않습니다. 운동을 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 관계가 필요합니다.

Enum 값은 고정되어 있으며 순서가 중요합니다.

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으로 그대로 다시 보내야 하며, exercise_ids_to_replace의 모든 id가 그 안에 있어야 합니다. 생성기는 user_equipment를 엄격히 따르지 않으므로 항상 사후 필터링하세요.

버스트는 챌린지됩니다. HTML 본문이 있는 403은 일시적이며 약 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개의 동시 요청은 429 없이 초당 약 32회를 유지했고 어떤 응답에도 rate limit 헤더가 없었습니다. 처리량이 필요하다면 여유가 있습니다.

운동 코퍼스는 이중 인덱스로 키가 지정됩니다. 기록된 세트와 카탈로그 항목이 서로 다른 id 공간을 사용하기 때문입니다. 이러한 이유로 reference.by_id()와 reference.by_external_id()가 모두 존재합니다.

문서

운동 카탈로그

build_reference.py는 추출된 Fitbod APK의 res/raw 디렉토리에서 data/exercise-reference.json을 빌드합니다: 약 1,400개의 운동(서면 지침 포함), 78개 장비 유형, 근육 그룹 매핑, 장비 중량 테이블이 포함됩니다. 해당 콘텐츠는 Fitbod 소유이므로 여기에 배포되지 않습니다. 직접 설치본에서 빌드하세요.

법적 고지

이 프로젝트는 문서화되지 않은 API를 사용하며, 자신의 계정만 건드리고 결제를 우회하지 않더라도 Fitbod의 서비스 약관을 위반할 가능성이 매우 높습니다. 이는 자신의 훈련 데이터와의 개인적 상호운용성을 위해 존재합니다. 자신의 계정에서 자신의 책임 하에 사용하고, 다른 사람의 계정에는 사용하지 마세요.

배너의 육각형 마크는 Fitbod의 시각적 정체성에서 영감을 받은 독창적인 그림이며 그들의 상표가 아닙니다. 이 프로젝트는 Fitbod와 어떤 방식으로도 제휴, 보증, 연결되어 있지 않습니다.

라이선스

MIT