Elite MCP

셀프 호스팅 Elite 인스턴스 — 운동, 식단, 유산소, 체중을 기록하는 개인 피트니스 트래커 — 에 AI 에이전트가 직접 실시간 읽기/쓰기 액세스할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

이 서버를 어떻게 사용할지 결정하기 위해 이 문서를 읽고 있는 에이전트라면: 어떤 도구를 호출하기 전에 전체 파일을 읽으십시오. 각 도구가做什么, 인수의 의미, 기대되는 단위/형식, 그리고 주의해야 할 부분(주로: 쓰기는 즉시 실제로 반영되며 실행 취소가 없음)을 다룹니다. 아래의 "데이터 모델 참고 사항" 및 "안전 참고 사항" 섹션은 도구 목록 자체만큼 중요합니다.

이것이 무엇이고, 무엇이 아닌지

Elite(앱)는 모든 데이터를 자체 SQLite 데이터베이스에 저장하며 일반 REST API 뒤에 있습니다 — 로컬 캐시 없음, 오프라인 큐 없음, 단일 진실 공급원. 이 MCP 서버는 해당 API 위의 얇은 프로토콜 어댑터입니다: 여기의 모든 도구 호출은 당신이 가리키는 특정하고 이미 실행 중인 Elite 인스턴스에 대한 하나(또는 두 개)의 HTTP 요청입니다. 자체 상태를 보유하지 않으며 캐싱도 하지 않습니다 — get_workout_history를 연속으로 두 번 호출하면 두 번 모두 새로운 읽기를 얻습니다.

일반 피트니스 API가 아니며, 다른 앱과 통신하지 않으며, 식품 데이터베이스 조회(OpenFoodFacts/USDA 검색)도 하지 않습니다 — 그 조회 로직은 Elite 웹 앱 자체의 클라이언트 측에 있으며 HTTP로 노출되지 않습니다. 이 사용자의 데이터에 아직 없는 음식을 기록해야 한다면, 이미 알고 있거나 사용자가 제공한 매크로로 log_food를 사용하십시오; 여기에는 "이름으로 음식 검색" 도구가 없습니다.

요구 사항

• URL을 알고 있는 실행 중인 Elite 인스턴스(예: http://192.168.1.50:8080, 또는 셀프 호스팅된 위치). 인스턴스를 새로 구성해야 한다면 Elite 저장소를 참조하십시오.

• Node.js 18 이상.

• 해당 Elite 인스턴스가 API_TOKEN으로 시작된 경우, 동일한 토큰이 필요합니다.

설정

git clone https://github.com/natyavidhan/elite-mcp.git
cd elite-mcp
npm install
cp .env.example .env   # then fill in ELITE_BASE_URL (and ELITE_API_TOKEN if the server needs one)

이것은 표준 stdio MCP 서버입니다 — MCP 클라이언트 자체의 구성에 의해 생성되도록 설계되었으며, 독립 실행형으로 열어두는 것이 아닙니다. 에이전트/클라이언트를 node /path/to/elite-mcp/index.js로 지정하고 ELITE_BASE_URL(및 선택적으로 ELITE_API_TOKEN)을 환경 변수로 설정하십시오. JSON 구성을 읽는 클라이언트(Claude Desktop, Claude Code 및 대부분의 다른 클라이언트는 이 형태를 따름)의 경우:

{
  "mcpServers": {
    "elite": {
      "command": "node",
      "args": ["/path/to/elite-mcp/index.js"],
      "env": {
        "ELITE_BASE_URL": "http://192.168.1.50:8080",
        "ELITE_API_TOKEN": ""
      }
    }
  }
}

JSON 구성 MCP 클라이언트가 없는 에이전트 런타임(예: 사용자 지정 오케스트레이터)의 경우, 동일한 두 환경 변수와 stdio를 통한 node index.js 생성이 전체 계약입니다 — 둘 다 짧은 index.js 및 src/client.js를 참조하십시오.

ELITE_BASE_URL이 설정되지 않으면 프로세스는 stderr에 오류를 기록하고 중단된 상태로 시작하는 대신 즉시 종료됩니다.

도구

총 20개 도구: 연결 확인 1개, 읽기 전용 분석 도구 11개, 조회 도구 1개, 쓰기 도구 7개. 모든 도구는 결과를 JSON 텍스트 블록으로 반환합니다; 실패(Elite에 연결할 수 없음, 잘못된 토큰, 404, 검증 오류)는 isError: true 및 {"error": "..."} 본문이 있는 일반 도구 결과로 반환됩니다 — MCP 연결을 중단시키지 않으므로 성공을 가정하지 말고 이를 확인하십시오.

연결

• check_connection — 인수 없음. Elite의 /api/health를 호출합니다. 다른 것이 실패하면 먼저 이것을 호출하십시오; 서버에 연결할 수 있는지와 AI 코치가 활성화되어 있는지(이 MCP 서버와는 무관하지만 올바른 인스턴스와 통신하고 있다는 유용한 신호) 알려줍니다.

분석(읽기 전용)

이것들은 Elite 자체 내장 AI 코치가 내부적으로 호출하는 것과 정확히 동일합니다 — 동일한 함수, 동일한 수학, 따라서 여기의 숫자는 항상 사용자가 앱에서 보는 것과 일치합니다.

• get_workout_history({ days? }) — 지난 N일(기본 30) 동안의 세션: 날짜, 운동, 세트, 총 볼륨.

• get_exercise_trend({ exerciseName, limit? }) — 한 운동에 대한 세션별 최고 중량 추이와 역대 PR. exerciseName은 퍼지 매칭(정확한 id, 정확한 이름 또는 부분 문자열)됩니다 — 추세를 읽기 위해 먼저 list_exercises가 필요하지 않습니다.

• get_personal_records({ limit? }) — 운동별 최고 중량 및 최고 단일 세트 볼륨, 무거운 순.

• get_muscle_volume({ date }) — 특정 하루의 근육별 볼륨(주동근 전체 크레딧, 보조근 절반 크레딧).

• get_weekly_muscle_summary({ days? }) — 지난 N일(기본 7) 동안의 근육별 총 볼륨, 순위 표시 — 부족하게 훈련된 부위를 찾는 데 사용.

• get_muscle_exercise_split({ muscle, days? }) — 한 근육의 볼륨을 구성하는 운동과 각각의 비율(예: "내 삼두 분할은 무엇인가"). muscle은 아래 나열된 열거형 값 중 하나여야 합니다.

• get_food_log({ date }) — 한 날짜에 기록된 모든 항목(매크로 포함)과 그날의 합계.

• get_nutrition_trend({ days? }) — 지난 N일(기본 7) 동안의 일일 칼로리/매크로 합계와 사용자가 설정한 일일 목표.

• get_cardio_summary({ days? }) — 지난 N일(기본 30) 동안의 유산소 세션과 개인 최고 기록.

• get_body_weight_trend({ days? }) — 지난 N일(기본 90) 동안의 기록과 현재/시작/변화/7일 평균.

• get_consistency({ days? }) — 지난 N일(기본 14) 동안 사용자가 운동, 식단, 유산소, 체중을 기록했는지 여부를 일별로 표시.

조회

• list_exercises({ query? }) — 전체 운동 카탈로그(내장 + 이 인스턴스의 사용자 지정 운동), 선택적으로 id 또는 이름에 대한 대소문자 구분 없는 부분 문자열 일치로 필터링. 정확한 exerciseId를 이미 모르는 경우 log_workout_set 전에 이것을 호출하십시오 — 카탈로그는 자유 텍스트가 아닌 barbell_bench_press와 같은 특정 id를 사용하며, log_workout_set은 실제 id가 아닌 것을 거부합니다.

쓰기

여기의 모든 쓰기는 실행 중인 Elite 인스턴스에 즉시 반영됩니다 — 실제 데이터에 사용하기 전에 아래 안전 참고 사항을 참조하십시오.

• log_workout_set({ date, exerciseId, reps, weightKg, rpe? }) — 한 세트를 기록합니다. 아직 없으면 해당 날짜의 운동 세션을 자동으로 생성합니다. 생성된 세트와 isPR: true/false를 반환합니다. rpe(인지된 운동 강도, 1–10)는 선택 사항입니다.

• delete_workout_set({ setId }) — 기록된 한 세트를 삭제합니다.

• delete_workout_session({ sessionId }) — 전체 세션 및 그 아래의 모든 세트를 삭제합니다. 확인 단계가 없습니다 — 이 도구는 말한 대로 정확히 수행합니다.

• log_food({ date, mealType, name, quantityG, calories, protein?, carbs?, fat? }) — 음식 항목을 기록합니다. 매크로는 quantityG에 대한 총량이며 100g당이 아닙니다(이 도구가 변환을 수행합니다). 내부적으로 manual 소스 음식 항목을 생성합니다.

• delete_food_log({ logId }) — 기록된 음식 항목 하나를 삭제합니다.

• log_cardio_session({ date, activityType, durationSeconds, distanceKm?, avgHeartRate?, caloriesBurned?, notes? }) — 유산소 세션을 기록합니다.

• log_body_weight({ date, weightKg, bodyFatPct?, notes? }) — 날짜별로 **업서트(upsert)**합니다: 이미 기록이 있는 날짜에 다시 기록하면 중복을 만들지 않고 덮어씁니다. 이것은 의도된 동작(Elite 앱 자체가 그렇게 동작함)이며 버그가 아닙니다.

데이터 모델 참고 사항

• 날짜는 항상 YYYY-MM-DD 문자열이며 시간 구성 요소나 시간대가 없습니다. 이 서버에는 "오늘" 헬퍼가 없습니다 — 사용자가 "오늘로 기록해 줘"라고 하면 도구를 호출하기 전에 직접 오늘 날짜를 확인하십시오.

• ID(sessionId, setId, logId, exerciseId 등)는 Elite 서버가 생성한(또는 운동의 경우 카탈로그에 정의된) 불투명 문자열입니다 — 직접 구성하거나 추측하지 마십시오. 이전 도구 결과(log_workout_set 응답은 실제 set.id 및 sessionId를 제공) 또는 list_exercises에서 가져오십시오.

• muscle 열거형(get_muscle_exercise_split용): chest, triceps, shoulder, lats, bicep, forearm, traps, quads, hamstrings, glutes, calves, abs.

• mealType: breakfast, lunch, dinner, snack.

• activityType: run, walk, cycle, swim, other.

• 중량은 킬로그램, 거리는 킬로미터, 시간은 초입니다 — 사용자가 Elite UI를 어떤 단위 체계로 표시하도록 설정했는지와 관계없이 항상 그렇습니다.

안전 참고 사항

• 실행 취소가 없습니다. delete_workout_set, delete_workout_session, delete_food_log는 사용자의 실제 훈련/영양 기록에 대한 실제적이고 즉각적인 삭제입니다. 추측적으로 또는 "어떻게 되는지 확인만" 삭제 도구를 호출하지 마십시오 — 사용자가 명시적으로 삭제를 요청하지 않는 한 먼저 사용자와 확인하십시오.

• log_body_weight는 오류를 내거나 묻지 않고 해당 날짜의 기존 항목을 조용히 덮어씁니다 — 사용자가 오늘 체중을 이미 기록했는지 확실하지 않으면 먼저 get_body_weight_trend를 호출하십시오.

• 이 서버는 단일 공유 ELITE_API_TOKEN(대상 인스턴스가 사용하는 경우) 외에는 인증을 수행하지 않습니다 — 해당 토큰이 부여하는 만큼의 액세스 권한을 가지며, 기본적으로는 모든 것에 액세스할 수 있습니다. 그에 따라 취급하십시오.

저장소 구조

index.js         entry point — starts the stdio MCP server
src/client.js     fetch wrapper around the target Elite instance's REST API
src/tools.js      every tool's schema + implementation

관련

• natyavidhan/elite — 트래커 자체. README에는 이 서버가 기반으로 하는 전체 REST API(/api/data/*, /api/workout/*, /api/analytics/* 등)가 문서화되어 있으며, 이 MCP 서버가 도구로 이미 노출하지 않는 것이 필요하면 참조하십시오.