Elite MCP

Un servidor MCP (Model Context Protocol) que da a un agente de IA acceso de lectura/escritura directo, en tiempo real y a una instancia de Elite autoalojada — un rastreador personal de fitness para entrenamientos, serie y comida, cardio y peso corporal.

Si eres un agente que lee esto para decidir cómo usar este servidor: lee el archivo completo antes de llamar a cualquier herramienta. En él se explica qué hace cada herramienta, qué significan sus argumentos, qué unidades y formatos se esperan y dónde están los bordes afilados (sobre todo: las escrituras son inmediatas y reales, no hay deshacer). Las secciones «Notas sobre el modelo de datos» y «Notas de seguridad» que vienen más abajo importan tanto como la propia lista de herramientas.

Qué es esto y qué no es

Elite (la app) lo guarda todo en su propia base de datos SQLite detrás de una API REST simple — sin caché local, sin cola de espera, sin conexión, una única fuente de verdad. Este servidor MCP es un adaptador de protocolo ligero sobre esa API: cada llamada a una herramienta aquí supone una (o dos) peticiones HTTP a una instancia de Elite concreta y ya en ejecución a la que apuntas. No mantiene estado propio y no hace calificación: llama a get_workout_history dos veces seguidas y obtendrás dos lecturas frescas.

No es una API general ni el servidor MCP es una API general de fitness, no se comunica con ninguna otra aplicación y no hace búsquedas en bases de datos de alimentos (sin OpenFoodFacts/USDA). Esa lógica de búsqueda está en el lado del cliente, dentro de la propia app web de Elite, y no se expone por HTTP. Si necesitas registrar un alimento que no esté ya en los datos de este usuario, usa log_food con macros que ya conozcas o que te dé el usuario; aquí no existen funciones de buscar un alimento por su nombre.

Requisitos

• Una instancia de Elite en ejecución de la que tengas la URL (p. ej. http://192.168.1.50:8080, o dondequiera que esté autoalojada). Mira en el repositorio de Elite si necesitas levantar una.

• Node.js 18+.

• Si esa instancia de Elite se inició con API_TOKEN, necesitarás el mismo token.

Configuración

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)

Esto es un servidor MCP stdio estándar: se espera que lo lanela la propia configuración de un cliente MCP, no que se ejecute solo ni que quede abierto. A punto el agente o cliente a node /path/to/elite-mcp/index.js con ELITE_BASE_URL (y opcionalmente ELITE_API_TOKEN) como variables de entorno digital. Para cliente que lee una configuración JSON (Claude Desktop, Claude Code y la mayoría de los demás siguen esta forma):

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

Para un entorno de ejecución de agente sin cliente MCP por JSON (un orquestador personalizado, por ejemplo), las mismas dos variables de entorno más lanzar node index.js por stdio son todo el contrato; ver recién index.js y src/client.js, ambos cortos.

Si ELITE_BASE_URL no está definida, the process logs an error to stderr and exits immediately rather than starting in a broken state.

Herramientas

Veinte herramientas en total: 1de comprobación de la conexión, 1 lectura 11 de analíticas (solo lectura), 1 búsqueda y 7 de escritura. Cada herramienta devuelve su resultado en forma de bloque de texto JSON; un fallo (Elite incalcán, token malo, 404, error de validación) llega como resultado de herramienta normal con isError: true y un cuerpo {"error": "..."} — no tumba la conexión MCP, así que compruébalo enveces de dar por hecho que el punto está bien.

Conexión

• check_connection — sin argumentos. Golpea al /api/health de Elite. Llama a esta herramienta primero si algo más falla; te dice si el servidor es alcanzado y si su AI Coach está activado (irrelevante para este servidor MCP, pero es la señal útil de que estáshablando con la instancia correcta).

Analíticas (solo lectura)

Estas son el reflejo exacto de lo que el AI Coach integrado de Elite usa internamente — mismas funciones, misma matemática — para que los números que ves aquí coincidan siempre con lo que el usuario ve en la app.

• get_workout_history({ days? }) — sesiones en los últimos N días (predefinido 30): fecha, ejercicios y series, volumen total.

• get_exercise_trend({ exerciseName, limit? }) — mejor peso por sesión para un ejercicio a lo largo del tiempo, más su récord histórico (PR). exerciseName se hace coincidir de forma difusa (con id exacto, nombre exacto o subcadena) — no hace falta que llames antes a list_exercises solo por leer un rastro.

• get_personal_records({ limit? }) — mejor peso y mejor volumen en una sola serie por ejercicio, más pesado primero.

• get_muscle_volume({ date }) — volumen músculo a músculo de un día concreto (músculos primarios con crédito completo, músculos secundarios con la mitad de crédito).

• get_weekly_muscle_summary({ days? }) — volumen total por músculo en los últimos N días (predefinido 7), ordenados de mayor a menor; úsalo para ver qué está poco entrenado.

• get_muscle_exercise_split({ muscle, days? }) — qué ejercicios forman el volumen de un músculo y qué parte le corresponde a cada uno (p. ej., «¿cómo se divide mi tríceps?»). muscle debe ser uno de los valores del enum que se enumeran a continuación.

• get_food_log({ date }) — todas las listas de un día, con macros y los totales del día.

• get_nutrition_trend({ days? }) — totales diarios de calorías y macros de los últimos N días (default 7) más los objetivos diarios configurados por el usuario.

• get_cardio_summary({ days? }) — sesiones de cardio de los últimos N días (default 30) más marcas personales.

• get_body_weight_trend({ days? }) — los últimos N días (default 90) con peso actual, inicial, cambio y promedio de 7 días.

• get_consistency({ days? }) — por día, y si el usuario registró un entrenamiento o comida, una tarjeta de cardio, o el peso corporal, en los últimos N días (default 14).

Búsqueda

• list_exercises({ query? }) — el catálogo completo de entradas (libros + ejercicios personalizados de esta instancia), opcionalfiltrado por coincidencia de subcadena sin distinguir mayúsculas/minúsculas en el id o el nombre. Llama a esta función antes de log_workout_set si no conoces exactamente elexerciseId — el catálogo usa ids específicos como barbell_bench_press, no texto libre, y log_workout_set rechazará cualquier cosa que no sea un identificador real.

Escrituras

Cada escritura de aquí produce efecto inmediato en la instancia de Elite en vivo — mira las Notas de seguridad más abajo antes de usarlas sobre datos reales de alguien.

• log_workout_set({ date, exerciseId, reps, weightKg, rpe? }) — registra una serie. Crea la sesión de entrenamiento de ese día automáticamente si aún no existe. Devuelve la serie creada, así como isPR: true/false. rpe (índice de esfuerzo percibido, 1–10) es opcional.

• delete_workout_set({ setId }) — elimina una serie registrada.

• delete_workout_session({ sessionId }) — elimina toda una sesión y todas las series que contiene. No hay paso de confirmación: la herramienta hace exactamente lo que dice.

• log_food({ date, mealType, name, quantityG, calories, protein?, carbs?, fat? }) — registra una entrada de comida. Los macros son el total respecto a quantityG, no por cada 100 g (esta herramienta hace la conversión por ti). Crea un elemento de comida de fuente manual entre bastidores.

• delete_food_log({ logId }) — elimina una entrada de comida registrada.

• log_cardio_session({ date, activityType, durationSeconds, distanceKm?, avgHeartRate?, caloriesBurned?, notes? }) — registra una sesión de cardio.

• log_body_weight({ date, weightKg, bodyFatPct?, notes? }) — hace upsert por fecha: si vuelve a registrar un día que ya tiene su propia entrada, la sobrescribirá en lugar de crear un duplicado. Esto es intencionado (es como la propia app de Elite), no un bug.

Notas sobre el modelo de datos

• Las fechas (dates) son siempre cadenas de caracteres YYYY-MM-DD, sin hora y sin zona horaria. No existe un «hoy» en este servidor — si un usuario dice “lo registro para hoy”, debes resolver tú mismo la fecha de hoy antes de invocar la herramienta.

• Los id (sessionId, setId, logId, exerciseId, etc.) son cadenas de caracteres opacas que genera el servidor de Elite (o, para los ejercicios, están en su propio catálogo) — nunca las construyas ni las adivines. Obtenlos del resultado de una llamada anterior (una respuesta de log_workout_set te da un set.id y un sessionId reales), o de list_exercises.

• El enum muscle (para 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.

• El peso es en kilogramos, las distancias en kilómetros y las duraciones en segundos — siempre, independientemente del sistema de unidades que el usuario tenga en la UI de Elite para mostrar los resultados.

Notas de seguridad

• No hay marcha atrás. delete_workout_set, delete_workout_session y delete_food_log son borrados reales, inmediatos, contra el historial de entrenamiento y de comida real del usuario. No llames a ningún método de borrado de manera especulativa ni «solo para ver qué ocurre» — confirma primero con el usuario, a menos que sea lo que pida, de forma explícita, hacerlo.

• log_body_weight lo reescribe en silencio cuando existe una entrada para esa fecha — en vez de emitir un error o pedir confirmación; si no estás seguro de si ya hay un peso de hoy, llama antes a get_body_weight_trend.

• Este servidor no cuenta con autorización más allá del único ELITE_API_TOKEN compartido (si la instancia de destino usa uno) — su acceso equivale exactamente a lo que ese token permite, que por defecto es todo. Aplícalo con el mismo cuidado.

Estructura del repositorio

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

Relacionado

• natyavidhan-elite — el rastreador en sí. Su README documenta la API REST completa sobre la que se apoya este servidor (/api/data/*, /api/workout/*, /api/analytics/*, etc.) en caso de que necesites algo que este servidor MCP no exponga aún como herramienta.