hevy-mcp-server

Servidor MCP para la API de seguimiento de entrenamientos Hevy. Da a un LLM acceso de lectura y escritura a entrenamientos, rutinas, plantillas de ejercicios, historial por ejercicio y mediciones corporales.

Cubre los 15 endpoints de la API pública de Hevy (v0.0.1) en 27 herramientas.

Requisitos

• Node.js 18+

• Una suscripción Hevy Pro — el acceso a la API es solo Pro

• Una clave API de https://hevy.com/settings?developer

Related MCP server: hevy-mcp-server

Instalación

pnpm install
pnpm run build

Configuración

Establece HEVY_API_KEY en la configuración de tu cliente MCP. Para Claude Desktop, en claude_desktop_config.json:

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp-server/dist/index.js"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

Modo remoto/HTTP, localmente:

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

Inspecciona las herramientas de forma interactiva:

HEVY_API_KEY=your-key pnpm run inspect

Despliegue (para conectores de Claude mobile / claude.ai)

Claude se conecta a conectores personalizados desde la nube de Anthropic, no desde tu dispositivo, por lo que mobile y claude.ai necesitan que esto sea accesible a través de HTTPS público. Claude Code y Claude Desktop no — usa stdio allí en su lugar.

1. Genera un secreto de ruta

openssl rand -hex 32

El servidor se niega a iniciar en una interfaz no loopback sin MCP_PATH_SECRET configurado, porque un endpoint público que contiene tu clave de Hevy es un proxy abierto a tu cuenta. Con él configurado, el endpoint se mueve a /mcp/<secret> y cualquier otra ruta devuelve 404 — incluido un secreto incorrecto, por lo que sondear el host no revela que allí vive un servidor MCP.

2. Despliega

El Dockerfile y railway.json incluidos funcionan tal cual en Railway, Render o Fly. La imagen establece TRANSPORT=http y HOST=0.0.0.0 y se ejecuta como un usuario no root. Establece dos variables en el panel de la plataforma:

PORT es inyectado por la plataforma. /healthz es una sonda de vida sin autenticación.

3. Verifica

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. Añade el conector

En claude.ai en un navegador — los conectores no se pueden añadir desde la aplicación móvil:

1. Personalizar → Conectores → Añadir conector personalizado

2. URL: https://your-app.up.railway.app/mcp/<secret>

3. En tu teléfono, abre un chat y actívalo en + → Conectores

Trata esa URL como una contraseña: es lo único que se interpone entre internet y tu registro de entrenamiento. Si se filtra, rota MCP_PATH_SECRET y vuelve a añadir el conector.

Herramientas

Workouts — hevy_list_workouts, hevy_get_workout, hevy_count_workouts, hevy_list_workout_events, hevy_create_workout, hevy_update_workout

Sessions — hevy_start_session, hevy_get_active_session, hevy_finish_session, hevy_cancel_session

Routines — hevy_list_routines, hevy_get_routine, hevy_create_routine, hevy_update_routine

Routine folders — hevy_list_routine_folders, hevy_get_routine_folder, hevy_create_routine_folder

Exercise templates — hevy_search_exercise_templates, hevy_list_exercise_templates, hevy_get_exercise_template, hevy_create_exercise_template

Progress — hevy_get_exercise_history, hevy_list_body_measurements, hevy_get_body_measurement, hevy_create_body_measurement, hevy_update_body_measurement

Account — hevy_get_user_info

Cada herramienta de lectura acepta response_format: "markdown" | "json". Markdown es el predeterminado y está optimizado para que lo lea un LLM; JSON es la carga útil estructurada completa. structuredContent siempre se rellena independientemente del formato.

Ejemplos

"¿Qué entrené esta semana?" → hevy_list_workouts con page_size=5. Devuelve títulos, duración, lista de ejercicios y volumen total por sesión.

"Registra el press de banca de hoy: 3x8 a 60kg" → hevy_search_exercise_templates con query="bench press" para obtener el id, luego hevy_create_workout con tres series de { weight_kg: 60, reps: 8 }.

"Empiezo piernas ahora" → hevy_start_session con title="Leg Day". La hora de inicio se sella en el servidor y la sesión aparece en Hevy como en curso. Cuando termines, hevy_finish_session con lo que realizaste la cierra con la duración real.

"¿Estoy ganando fuerza en sentadillas?" → hevy_search_exercise_templates con query="squat", luego hevy_get_exercise_history con un start_date. Devuelve cada serie registrada de más reciente a más antigua, además de la mejor serie por 1RM estimado.

Notas de diseño

Buscar antes de escribir. Hevy no tiene búsqueda de ejercicios en el servidor, pero cada escritura necesita un exercise_template_id. hevy_search_exercise_templates recorre el catálogo (hasta 30 páginas de 100) y filtra localmente por título, grupo muscular, equipo y solo personalizados. Apunta al modelo a esta herramienta primero — los ids no se pueden adivinar.

Las actualizaciones son reemplazos, no parches. hevy_update_workout, hevy_update_routine y hevy_update_body_measurement sobrescriben todo el recurso; cualquier cosa omitida se elimina o se anula. Los tres llevan destructiveHint: true, y sus descripciones le dicen al modelo que lea primero el estado actual. Estas son las únicas tres herramientas destructivas — la API de Hevy no tiene endpoints de eliminación.

Las sesiones en vivo son una convención de título, no un estado del servidor. La API de Hevy no tiene un endpoint de inicio de entrenamiento y no puede controlar el temporizador de la aplicación, por lo que hevy_start_session crea un entrenamiento real de antemano titulado 🔴 En curso — <title>, y hevy_finish_session lo reescribe con la hora de finalización real. Ese marcador es el único identificador que persiste — el servidor no mantiene estado entre solicitudes, por lo que cualquier chat en cualquier dispositivo encuentra la sesión abierta escaneando los entrenamientos recientes. El costo es que una sesión sin terminar permanece visible en el registro, y como Hevy no expone eliminación, hevy_cancel_session solo puede volver a etiquetarla, nunca eliminarla.

Todo es en kilogramos. La API no tiene campo de unidad. Los campos de entrada se llaman weight_kg para que no haya ambigüedad sobre lo que envía el modelo, y la salida en markdown muestra ambos (60 kg (132.3 lb)) para que un lector estadounidense no tenga que convertir mentalmente.

Los límites de tamaño de página se aplican en el cliente. Hevy devuelve un 400 simple para una página demasiado grande. Los esquemas de Zod limitan cada endpoint a su límite documentado (10 para la mayoría, 100 para plantillas de ejercicios), para que el modelo reciba un mensaje preciso en lugar de una solicitud fallida.

Los errores se resuelven en próximas acciones. Un 404 nombra la herramienta que produce ids válidos para ese recurso. Un 409 en una medición corporal apunta a la herramienta de actualización. Un 403 explica que el acceso a la API requiere Pro.

Esquemas de salida permisivos. La documentación de Hevy advierte que esta API 0.0.1 puede cambiar su estructura sin previo aviso. Los esquemas de salida usan passthrough() con campos opcionales para que una adición de campo aguas arriba no se convierta en un fallo duro de la herramienta.

Estructura del proyecto

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

Advertencias

• La API de Hevy es oficialmente versión 0.0.1 y su propia documentación advierte que la estructura puede cambiar o ser abandonada.

• La carpeta de una rutina no se puede cambiar después de la creación — el endpoint de actualización no acepta folder_id.

• El filtrado por equipo en la búsqueda coincide con el título del ejercicio, ya que la API no expone el equipo como campo en las plantillas.

• hevy_create_exercise_template devuelve un id numérico, a diferencia de los ids de cadena utilizados en el resto de la API.

Pruebas

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

Ambas suites se ejecutan contra un mock local, por lo que no se necesita clave API ni acceso a red.