Elite MCP

MCP-сервер (Model Context Protocol), который предоставляет ИИ-агенту прямой доступ для чтения и записи в реальном времени к самостоятельно размещённому экземпляру Elite — персональному фитнес-трекеру для тренировок, питания, кардио и массы тела.

Если вы агент, читающий это, чтобы решить, как использовать этот сервер: прочитайте весь файл перед вызовом любого инструмента. В нём описано, что делает каждый инструмент, что означают его аргументы, какие единицы измерения/форматы ожидаются и где находятся острые углы (в основном: записи выполняются немедленно и по-настоящему, отмены нет). Разделы «Примечания к модели данных» и «Примечания по безопасности» ниже важны не меньше, чем сам список инструментов.

Что это такое и чем не является

Elite (приложение) хранит всё в собственной базе данных SQLite за простым REST API — без локального кэша, без офлайн-очереди, один источник истины. Этот MCP-сервер — тонкий протокольный адаптер поверх этого API: каждый вызов инструмента здесь — это один (или два) HTTP-запрос к конкретному, уже запущенному экземпляру Elite, на который вы его нацеливаете. Он не хранит собственного состояния и не кэширует — вызовите get_workout_history дважды подряд и получите два свежих чтения.

Это не универсальный фитнес-API, он не общается с другими приложениями и не выполняет поиск по базе продуктов (нет поиска OpenFoodFacts/USDA) — эта логика поиска живёт на стороне клиента в самом веб-приложении Elite и не доступна через HTTP. Если вам нужно записать продукт, которого ещё нет в данных этого пользователя, используйте log_food с макросами, которые вы уже знаете или которые даст пользователь; здесь нет инструмента «поиск продукта по названию».

Требования

• Запущенный экземпляр Elite, URL которого у вас есть (например, 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": ""
      }
    }
  }
}

Для агентной среды выполнения без MCP-клиента с JSON-конфигурацией (например, кастомного оркестратора) весь контракт — это те же две переменные окружения плюс запуск node index.js через stdio — см. index.js и src/client.js, оба короткие.

Если ELITE_BASE_URL не задан, процесс выводит ошибку в stderr и немедленно завершается, а не запускается в нерабочем состоянии.

Инструменты

Всего 20 инструментов: 1 проверка подключения, 11 аналитических инструментов только для чтения, 1 инструмент поиска и 7 инструментов записи. Каждый инструмент возвращает результат в виде JSON-текстового блока; сбой (Elite недоступен, неверный токен, 404, ошибка валидации) возвращается как обычный результат инструмента с isError: true и телом {"error": "..."} — это не приводит к падению MCP-соединения, поэтому проверяйте это, а не предполагайте успех.

Подключение

• check_connection — без аргументов. Обращается к /api/health Elite. Вызывайте его первым, если что-то ещё не работает; он сообщает, доступен ли сервер вообще и включён ли его AI Coach (не относится к этому MCP-серверу, но полезный сигнал, что вы общаетесь с правильным экземпляром).

Аналитика (только чтение)

Они точно повторяют то, что встроенный AI Coach в Elite вызывает внутри себя — те же функции, та же математика, поэтому числа здесь всегда будут совпадать с тем, что пользователь видит в приложении.

• get_workout_history({ days? }) — тренировки за последние N дней (по умолчанию 30): дата, упражнения, подходы, общий объём.

• get_exercise_trend({ exerciseName, limit? }) — лучший вес за тренировку для одного упражнения в динамике, плюс его абсолютный личный рекорд. 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 или названии. Вызывайте его перед log_workout_set, если вы ещё не знаете точный exerciseId — в каталоге используются конкретные id, например barbell_bench_press, а не произвольный текст, и 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, а не на 100 г (этот инструмент сам делает пересчёт). В фоне создаётся продукт с источником 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.

Примечания по безопасности

• Отмены нет. 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-сервер ещё не предоставляет как инструмент.