Hevy MCP

Servidor MCP de Hevy

CLI de Hevy

¿Prefieres la terminal? El paquete independiente @chrisdoc/hevy-cli lee entrenamientos, rutinas, ejercicios y mediciones corporales directamente desde la API de Hevy, y puede crear o actualizar esos recursos con confirmación explícita. La eliminación no está soportada.

npm install -g @chrisdoc/hevy-cli
export HEVY_API_KEY=your-hevy-api-key

hevy workouts list --page-size 10
hevy summary --weeks 4

Añade --json a cualquier comando para scripts y pipelines. La CLI es un cliente independiente de la API de Hevy, no un envoltorio de MCP. Consulta packages/cli/README.md para la referencia completa de comandos, el comportamiento de paginación y los códigos de salida.

hevy-mcp es un servidor de Protocolo de Contexto de Modelo (MCP) de código abierto para la aplicación de fitness y seguimiento de entrenamientos Hevy. Permite que los asistentes de IA lean, analicen, creen y actualicen tus entrenamientos, rutinas, plantillas de ejercicios y mediciones corporales de Hevy mediante solicitudes autenticadas a la API de Hevy.

El adaptador Node stdio/HTTP y el Worker de Cloudflare comparten las mismas herramientas MCP. Consulta modos de implementación para elegir un transporte, o arquitectura para conocer la propiedad del espacio de trabajo, los ámbitos de ejecución y las API de incrustación compatibles.

Se requiere una clave de API de Hevy, disponible con Hevy PRO.

Véalo en acción

_{Haz clic en la vista previa para reproducir la demo de 18 segundos en calidad completa.}

En la demo, el asistente recupera datos reales de Hevy y responde una pregunta de entrenamiento de varias partes con evidencia del historial de entrenamientos del usuario.

¿Qué puedes hacer con él?

• Analizar el progreso del entrenamiento: resume de 1 a 12 semanas de entrenamientos y mediciones corporales en una sola llamada de herramienta.
• Hacer preguntas en lenguaje natural: encuentra sesiones recientes, ejercicios entrenados con frecuencia, brechas de consistencia, detalles de rutinas o historial de ejercicios.
• Planificar y registrar entrenamientos: crea o actualiza entrenamientos, rutinas, carpetas de rutinas, ejercicios personalizados y mediciones corporales.
• Buscar sin respuestas enormes: descubre rutinas y plantillas de ejercicios con resultados compactos y aptos para IA.
• Conectarte desde tu cliente MCP preferido: usa el endpoint Streamable HTTP alojado o ejecútalo localmente con Codex, Claude Desktop, Cursor y otros clientes.
• Empezar sin instalar nada: conéctate directamente al Worker de Cloudflare de producción: no se requiere Node.js, descarga de paquetes ni contenedor Docker.
• Mantener el control local cuando lo desees: ejecuta el mismo servidor con npx, bunx, o la imagen oficial de Docker.

Prueba a preguntar:

Analiza mi entrenamiento de las últimas seis semanas. Muestra entrenamientos por semana, mis ejercicios entrenados con más frecuencia, cualquier brecha o inconsistencia evidente, y cita la evidencia de entrenamiento que usaste.

Encuentra mi rutina de día de empuje y muestra sus ejercicios y series.

Compara mis mediciones corporales recientes con mi consistencia de entrenamiento.

Crea un entrenamiento completado a partir de mi rutina guardada. Pídeme los resultados de series faltantes antes de escribirlo en Hevy.

Integración con Claude

El repositorio incluye un plugin de Claude que se conecta al endpoint MCP alojado con OAuth sin incrustar la clave de API de Hevy del usuario.

Claude.ai y Claude Desktop

En Claude, abre Configuración → Conectores → Añadir conector personalizado e introduce:

https://mcp.hevy-mcp.dev/mcp

Completa el flujo de OAuth e introduce la clave de API de Hevy cuando se te solicite. El mismo endpoint remoto puede ser utilizado por Claude Desktop y otros clientes que admitan conectores MCP remotos.

Claude Code y Cowork

El plugin de Claude está definido por .claude-plugin/plugin.json y .mcp.json. Instálalo desde este repositorio público o desde el Directorio de Plugins de Claude después de su publicación. Añade el conector MCP de Hevy alojado y la habilidad de entrenamiento de Hevy.

Consulta la política de privacidad para conocer los detalles del manejo de datos del servicio alojado.

Inicio rápido

1. Obtén tu clave de API de Hevy

Crea una clave de API en la configuración de API de Hevy y luego guárdala en un lugar seguro. El acceso a la API actualmente requiere una suscripción a Hevy PRO.

2. Conecta hevy-mcp a tu cliente

El endpoint alojado de Cloudflare es la forma más rápida de empezar. Se ejecuta de forma remota, por lo que tu cliente no necesita Node.js, Bun, Docker ni un proceso de servidor local.

Conéctate al endpoint alojado

URL de producción:

https://mcp.hevy-mcp.dev/mcp

El endpoint utiliza Streamable HTTP. Envía tu clave de API de Hevy como token de portador en cada solicitud.

Codex

La CLI de Codex, la aplicación de escritorio de Codex y la extensión de IDE comparten la misma configuración de MCP. Haz que tu clave de API de Hevy esté disponible en el entorno que inicia Codex y luego añade el servidor alojado:

export HEVY_API_KEY=your-hevy-api-key
codex mcp add hevy \
  --url https://mcp.hevy-mcp.dev/mcp \
  --bearer-token-env-var HEVY_API_KEY

Codex almacena el nombre de la variable de entorno, no la clave en sí, en su configuración de MCP. Reinicia Codex o inicia una nueva sesión y luego ejecuta codex mcp list para verificar que el servidor está configurado.

Otros clientes Streamable HTTP

Los clientes que aceptan una URL MCP remota y encabezados fijos suelen usar esta forma:

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

Las claves de configuración exactas varían según el cliente. El servidor alojado requiere soporte para Streamable HTTP y un encabezado Authorization fijo.

[!IMPORTANTE] Trata el valor del portador como una contraseña. El Worker lo valida con Hevy en cada solicitud, no lo almacena y lo reenvía a Hevy solo como el encabezado api-key requerido.

Ejecuta localmente en su lugar

Elige stdio local si prefieres ejecutar el servidor en tu propia máquina o si tu cliente no puede adjuntar un encabezado de autorización fijo a las solicitudes MCP remotas.

Codex

codex mcp add hevy \
  --env HEVY_API_KEY=your-hevy-api-key \
  -- npx -y hevy-mcp

Claude Desktop o Cursor

Añade esta entrada mcpServers a la configuración de tu cliente:

{
	"mcpServers": {
		"hevy": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

Google Antigravity

Hay dos formas de configurar el servidor MCP de Hevy para Google Antigravity (agy):

Opción A: Instalación automática del plugin (recomendada)

Esto utiliza el sistema de plugins integrado:

El plugin lee el mcp_config.json de la raíz del repositorio para iniciar el servidor stdio local. Esa configuración no contiene intencionalmente ninguna clave de API; el servidor hereda HEVY_API_KEY del entorno del host como se describe a continuación. Esto es independiente de la configuración manual global del usuario descrita a continuación y de la .mcp.json del repositorio, que configura HTTP/OAuth alojado.

1. Instala el plugin:

   agy plugin install https://github.com/chrisdoc/hevy-mcp
   

2. Proporciona el HEVY_API_KEY en el entorno de shell de tu host para que el proceso hijo de la CLI pueda heredarlo:

   • Persistente: Guarda la variable de entorno HEVY_API_KEY en las configuraciones de tu sistema/shell:
     • macOS / Linux: Añádela a las configuraciones de tu perfil de shell (por ejemplo, ~/.zshrc o ~/.bashrc):

       export HEVY_API_KEY="your-actual-api-key"
       

     • Windows: Añádela a las Variables de Entorno de Usuario o del Sistema. En PowerShell, puedes ejecutar:

       [Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")
       

   • Temporal (solo sesión): Si no deseas persistir la clave, expórtala en tu sesión de terminal activa antes de ejecutar agy:

     export HEVY_API_KEY="your-actual-api-key"
     

Opción B: Configuración manual (sin plugin)

Si prefieres configurarlo estáticamente mediante el archivo de configuración global:

1. Abre tu archivo de configuración MCP global:

   • Ubicación: ~/.gemini/config/mcp_config.json

2. Añade el bloque de configuración hevy bajo la clave mcpServers. Asegúrate de fusionar esta entrada con cualquier servidor existente que hayas configurado en lugar de reemplazar todo el contenido del archivo:

   {
   	"mcpServers": {
   		"hevy": {
   			"command": "npx",
   			"args": ["-y", "hevy-mcp"],
   			"env": {
   				"HEVY_API_KEY": "your-actual-api-key"
   			}
   		}
   	}
   }
   

Ubicaciones comunes de configuración local:

• Claude Desktop en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop en Windows: %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

Reinicia o vuelve a conectar el cliente después de guardar el archivo.

Cualquier cliente MCP stdio

Configura tu cliente para iniciar este comando con HEVY_API_KEY en el entorno del proceso hijo:

npx -y hevy-mcp

npx requiere Node.js 20 o más reciente. Reinicia o vuelve a conectar tu cliente después de guardar su configuración.

{
	"mcpServers": {
		"hevy": {
			"command": "bunx",
			"args": ["hevy-mcp@latest"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

export HEVY_API_KEY=your-hevy-api-key
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

{
	"mcpServers": {
		"hevy": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"--env-file",
				"/absolute/path/to/hevy-mcp.env",
				"ghcr.io/chrisdoc/hevy-mcp:latest"
			]
		}
	}
}

También puedes añadir el servidor npm a clientes compatibles con add-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

3. Haz tu primera pregunta

Prueba una de estas después de reiniciar o volver a conectar tu cliente MCP:

• "Dame un resumen de entrenamiento de las últimas cuatro semanas".
• "¿Qué rutinas tengo guardadas en Hevy?"
• "Muestra mis tres entrenamientos más recientes".
• "Encuentra plantillas de ejercicios que contengan sentadilla".
• "¿Qué cuenta de Hevy está conectada?"

Tu asistente debería pedir aprobación antes de las herramientas de mutación cuando el cliente admita confirmaciones de herramientas.

Cómo funciona

Hosted:  Your AI assistant  →  Streamable HTTP  →  Cloudflare Worker  →  Hevy API
Local:   Your AI assistant  →  MCP over stdio   →  local hevy-mcp     →  Hevy API

El endpoint alojado crea un servidor MCP y un cliente de Hevy nuevos para cada solicitud. La autenticación directa de portador utiliza la clave de Hevy proporcionada y almacena en caché la validación exitosa durante 15 minutos sin persistir la clave sin procesar. OAuth en su lugar almacena la clave cifrada en una concesión. Ninguna de las dos vías crea una sesión de usuario MCP compartida. El servidor local sigue el mismo contrato de herramientas pero recibe la clave de Hevy a través de su entorno de proceso.

En cualquier modo, las herramientas de lectura recuperan datos; las herramientas de mutación crean o reemplazan datos solo cuando tu asistente las llama.

Prompts guiados

Estos prompts MCP proporcionados por el servidor coordinan flujos de trabajo comunes de varios pasos:

Herramientas

hevy-mcp registra 23 herramientas. Las herramientas de solo lectura son seguras para la exploración; las herramientas de creación y actualización se exponen con anotaciones de mutación MCP para que los clientes compatibles puedan solicitar confirmación.

| Entrenamientos | get-workout-events | Listar eventos de actualización y eliminación de entrenamientos desde una marca de tiempo. | | Entrenamientos | create-workout | Crear un entrenamiento completado en Hevy. | | Entrenamientos | update-workout | Modificar metadatos de entrenamiento por ID; is_private es obligatorio, mientras que otros campos omitidos y todos los ejercicios permanecen sin cambios. | | Entrenamientos | replace-workout-exercises | Reemplazar todos los ejercicios y series; is_private es obligatorio y se actualiza, mientras que otros metadatos de entrenamiento permanecen sin cambios. | | Rutinas | search-routines | Buscar títulos de rutinas y devolver metadatos compactos para descubrimiento. | | Rutinas | get-routines | Listar rutinas de entrenamiento personalizadas y predeterminadas. | | Rutinas | get-routine | Obtener una rutina y su configuración de ejercicios por ID. | | Rutinas | create-routine | Crear una rutina de entrenamiento reutilizable. | | Rutinas | update-routine | Reemplazar el contenido de una rutina existente. |

| Carpetas de rutinas | get-routine-folder | Obtener metadatos de una carpeta de rutinas por ID. | | Carpetas de rutinas | create-routine-folder | Crear una carpeta de rutinas. |

| Plantillas de ejercicios | get-exercise-template | Obtener metadatos completos de una plantilla de ejercicio por ID. | | Plantillas de ejercicios | search-exercise-templates | Buscar el catálogo completo de ejercicios por subcadena de título. | | Plantillas de ejercicios | create-exercise-template | Crear una plantilla de ejercicio personalizada. | | Historial de ejercicios | get-exercise-history | Obtener series realizadas anteriormente para una plantilla de ejercicio. | | Mediciones corporales | get-body-measurements | Listar mediciones corporales con fecha. | | Mediciones corporales | get-body-measurement | Obtener la entrada de medición corporal para una fecha. | | Mediciones corporales | create-body-measurement | Crear una medición corporal con fecha. | | Mediciones corporales | update-body-measurement | Actualizar la medición corporal para una fecha existente. | | Diagnóstico | feedback | Informar una descripción concisa y segura para la privacidad de un problema o comportamiento inesperado. |

create-routine y update-routine requieren un envoltorio routine de nivel superior con un arreglo exercises no vacío; cada ejercicio debe contener al menos una serie, y los campos usan snake_case en cada nivel:

{
	"routine": {
		"title": "Full Body A",
		"folder_id": 123,
		"notes": "First four exercises are the minimum viable workout",
		"exercises": [
			{
				"exercise_template_id": "30E293E3",
				"superset_id": null,
				"rest_seconds": 120,
				"notes": "Controlled active ROM",
				"sets": [
					{
						"type": "normal",
						"rep_range": {
							"start": 6,
							"end": 10
						}
					}
				]
			}
		]
	}
}

La API de Hevy actualmente no expone endpoints de eliminación para entrenamientos, rutinas, carpetas de rutinas, plantillas de ejercicios o mediciones corporales, por lo que no hay herramientas de eliminación correspondientes.

Recursos

Endpoint alojado en Cloudflare

El servidor MCP de producción está disponible en:

https://mcp.hevy-mcp.dev/mcp

Es la forma más rápida de usar hevy-mcp: no hay nada que instalar o mantener ejecutándose localmente, y expone las mismas 23 herramientas que el paquete npm y la imagen Docker.

El Worker de Cloudflare usa Streamable HTTP sin estado en POST /mcp. Los clientes deben enviar su clave de API de Hevy como un encabezado de autorización fijo:

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

En esta configuración, el valor del portador es su clave de API de Hevy, no un token OAuth. El Worker almacena en caché la validación exitosa durante 15 minutos bajo una clave hash, no persiste la clave sin procesar en esta ruta directa, y la reenvía upstream solo como el encabezado api-key requerido por Hevy.

OAuth para Claude.ai y otros clientes MCP remotos

El Worker de producción alojado está implementado con un enlace de espacio de nombres OAUTH_KV, por lo que expone una capa completa de OAuth 2.1 para clientes que no pueden enviar un encabezado fijo, como los conectores personalizados de Claude.ai. Los Workers autoalojados pueden optar por seguir la configuración de OAUTH_KV en CONTRIBUTING.md:

• Metadatos de descubrimiento RFC 8414 / RFC 9728 bajo /.well-known/
• Documentos de metadatos de ID de cliente (CIMD), con registro dinámico de clientes (/register) como respaldo, e intercambio de tokens PKCE (/token)
• Una página de /authorize donde pegas tu clave de API de Hevy una vez; la clave se valida con Hevy y se almacena cifrada dentro de la concesión OAuth

Agrega la URL del Worker que termina en /mcp como un conector personalizado de Claude.ai y completa el flujo de autorización en el navegador. Las solicitudes directas Authorization: Bearer <hevy-api-key> siguen funcionando sin cambios — la capa OAuth es puramente aditiva. Revocar o rotar tu clave de Hevy previene el acceso posterior a la API de Hevy con esa clave; no elimina por sí misma las concesiones almacenadas ni borra inmediatamente la validación en caché.

Los tokens de acceso OAuth duran siete días y los tokens de actualización duran 30 días. Esto reduce las escrituras en KV de actualizaciones horarias frecuentes mientras preserva la actualización automática para clientes compatibles.

El endpoint no expone SSE heredado ni un flujo de eventos GET. Sin la capa OAuth opcional, los clientes que requieren descubrimiento OAuth, registro dinámico, CIMD o actualización de tokens no son compatibles a menos que puedan enviar el encabezado personalizado fijo anterior.

Autoalojar el Worker

Un clon limpio puede implementar la configuración portable de TypeScript de Cloudflare con pnpm --dir packages/worker exec cf deploy y recibir una URL workers.dev. OAuth requiere tu propio espacio de nombres OAUTH_KV; dominios personalizados, rutas y destinos de observabilidad son configuraciones opcionales propiedad de la cuenta. Consulta CONTRIBUTING.md para la configuración y para la distinción entre autoalojamiento y los entornos nombrados solo para mantenedores.

Consulta CONTRIBUTING.md para implementar el Worker de Cloudflare para Streamable HTTP autoalojado.

Configuración avanzada

El ejecutable local de Node usa stdio por defecto. Opta por Streamable HTTP local con:

HEVY_API_KEY=your-hevy-api-key npx hevy-mcp --transport http --host 127.0.0.1 --port 3000

El endpoint MCP local es http://127.0.0.1:3000/mcp; los enlaces no loopback requieren la variable de entorno separada HEVY_MCP_HTTP_BEARER_TOKEN. Una implementación de Docker debe publicar el puerto explícitamente:

docker run --rm -p 3000:3000 -e HEVY_API_KEY -e HEVY_MCP_HTTP_BEARER_TOKEN \\
  ghcr.io/chrisdoc/hevy-mcp:latest --transport http --host 0.0.0.0 --port 3000

Este modo HTTP de Node es distinto del endpoint HTTP del Worker de Cloudflare sin estado descrito anteriormente: el servidor de Node posee sesiones de cliente con estado, mientras que el Worker está diseñado para implementación alojada y no importa código de Node.

Comportamiento de caché

search-exercise-templates y hevy://exercise-templates comparten una caché de catálogo en memoria a nivel de servidor:

• Las entradas viven durante cinco minutos, y la caché contiene como máximo un catálogo.
• Las solicitudes concurrentes de catálogo comparten una búsqueda en curso cuando es posible.
• search-exercise-templates acepta refresh: true para invalidar la caché.
• Cada solicitud al Worker alojado obtiene una caché de catálogo nueva, evitando compartir entre claves.
• Cada sesión HTTP local posee su propio servidor MCP y caché de catálogo; las cachés no se comparten entre sesiones.

Telemetría local de Node y privacidad

Las compilaciones de Node publicadas habilitan la telemetría del proyecto de forma predeterminada. Las ejecuciones de código fuente sin compilar (como scripts de desarrollo y de prueba) la deshabilitan a menos que HEVY_MCP_TELEMETRY=1 se establezca explícitamente. Esto es solo comportamiento local de Node; el Worker de Cloudflare no importa la telemetría de Node. Establece HEVY_MCP_TELEMETRY=0 antes de lanzar Node para deshabilitar toda la telemetría del proyecto en cualquiera de los modos. En las compilaciones publicadas, cada valor excepto el literal 0 conserva el valor predeterminado habilitado.

La capa de ciclo de vida de Node con ámbito adquiere la telemetría; importar el paquete permanece sin efectos secundarios. Las ejecuciones de fuente habilitadas usan el entorno de Sentry development; las compilaciones publicadas usan production. Establece SENTRY_ENVIRONMENT para anular esta etiqueta, por ejemplo a qa o staging. La configuración maestra tiene prioridad sobre SENTRY_DSN y las credenciales empaquetadas o de tiempo de ejecución OTEL_COLLECTOR_TOKEN, por lo que la ruta deshabilitada no crea exportadores de telemetría ni lectores periódicos de métricas y no realiza solicitudes de red de telemetría. SENTRY_DSN sigue siendo una configuración solo de Sentry; cuando la telemetría está habilitada, un valor vacío deshabilita solo la exportación de Sentry.

Cuando está habilitada, los errores accionables se envían al proyecto de Sentry configurado por SENTRY_DSN; el rastreo de rendimiento de Sentry está deshabilitado. Los mensajes de excepción y los seguimientos de pila están limitados y depurados antes de la exportación. Establece HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 para mantener los rastreos estructurales y las métricas mientras se suprimen esos detalles. Los rastreos y las métricas continúan enviándose al colector en https://otel.chrisdoc.dev/v1/traces y https://otel.chrisdoc.dev/v1/metrics. El proyecto usa su propio OpenTelemetry Collector; los destinos posteriores se configuran en esa infraestructura. Las métricas se exportan cada 30 segundos. Consulta la documentación de observabilidad para la exportación OTLP de Cloudflare y el rastreo de dominios.

La clave API sin procesar nunca se exporta. La telemetría ordinaria de herramientas puede incluir un seudónimo HMAC corto y determinista derivado de la clave para correlación; feedback usa una ruta separada no observada. Un ID de diagnóstico por fallo y un ID de rastreo OTel pueden adjuntarse a errores accionables. Consulta el diccionario de datos de telemetría para los campos de telemetría limitados y el contrato de privacidad.

Los mensajes de excepción y los seguimientos de pila se tratan como detalles de diagnóstico: tienen límite de longitud, se depuran en busca de credenciales, URL y rutas de inicio locales, y se eliminan por completo cuando HEVY_MCP_TELEMETRY_DIAGNOSTICS=0. Los prompts, argumentos de herramientas, resultados de herramientas, cuerpos de solicitud, claves API, identificadores/consultas sin procesar, fechas exactas, contenido de entrenamientos/rutinas/carpetas/plantillas/mediciones corporales, nombres/títulos/descripciones/notas, valores de medición, metadatos arbitrarios de clientes y rutas de endpoint no normalizadas siguen prohibidos.

Seguridad y mutaciones

• Mantén HEVY_API_KEY fuera del control de versiones, URL, registros y capturas de pantalla.
• Los clientes locales proporcionan la clave a través del entorno del proceso hijo.
• Los clientes alojados directos envían la clave de Hevy solo en el encabezado Authorization: Bearer; la validación exitosa se almacena en caché, pero la clave sin procesar no se persiste. Las concesiones OAuth almacenan la clave cifrada. Ambas rutas la envían a Hevy solo como el encabezado api-key.
• Las solicitudes MCP del navegador deben ser del mismo origen o coincidir con un origen exacto en la lista permitida. La lista permitida predeterminada incluye Claude.ai, ChatGPT, VS Code para la Web y github.dev; las implementaciones autoalojadas pueden anularla con MCP_ALLOWED_ORIGINS. Consulta modos de implementación para la excepción del formulario de autorización OAuth.
• El desarrollo local puede copiar .dev.vars.example a .dev.vars para deshabilitar la validación de Origen para MCP Inspector. Los Workers de vista previa de PR usan la misma configuración solo de desarrollo porque sus orígenes de navegador son dinámicos. Nunca establezcas MCP_DISABLE_ORIGIN_CHECK=true en un Worker de producción.
• Las operaciones de creación pueden producir duplicados cuando se reintentan. Las actualizaciones de rutinas reemplazan el contenido; las actualizaciones de metadatos de entrenamientos conservan los campos omitidos y los ejercicios, mientras que replace-workout-exercises reemplaza todos los ejercicios y conjuntos. Revisa las entradas de herramientas y usa confirmaciones del cliente.

Solución de problemas

• El servidor no aparece: reinicia o vuelve a conectar tu cliente MCP después de cambiar su configuración.
• npx falla: confirma que Node.js 20 o superior está instalado, luego ejecuta npx -y hevy-mcp --version en una terminal.
• Codex no puede ver el servidor: ejecuta codex mcp list, luego inicia una nueva sesión de Codex después de confirmar que la entrada hevy existe.
• La API de Hevy devuelve 401: la clave es inválida, expiró, fue revocada o está mal configurada. Verifica o crea una clave activa en la configuración de API de Hevy, luego reinicia el cliente.
• La autenticación alojada falla: confirma que la clave pertenece a una cuenta Hevy PRO y se envía como Authorization: Bearer <HEVY_API_KEY>.
• La autenticación local falla: confirma que la clave está activa y disponible para el proceso hijo de MCP como HEVY_API_KEY.
• Necesitas diagnósticos: establece HEVY_MCP_DEBUG=1. La salida de diagnóstico va a stderr y no interfiere con los mensajes MCP en stdout.

Si encuentras un error o tienes una solicitud de función, abre un issue.

Contribuciones

Las contribuciones son bienvenidas. La configuración del desarrollador, los carriles de prueba, los flujos de trabajo de clientes generados, la implementación del Worker de Cloudflare y las reglas de solicitudes de extracción están documentadas en CONTRIBUTING.md.

Usa mise para las versiones fijadas de Node.js y pnpm, luego ejecuta el carril de pruebas unitarias determinista. No necesita una clave API de Hevy en vivo:

MISE_AUTO_INSTALL=false mise install
MISE_AUTO_INSTALL=false mise exec -- pnpm install
MISE_AUTO_INSTALL=false mise exec -- pnpm run test:unit

Licencia y agradecimientos

• Licencia: MIT
• Créditos: Model Context Protocol y Hevy Fitness