hevy-mcp

Conecta a Claude con tu registro de entrenamiento de Hevy.

hevy-mcp es un servidor del Protocolo de Contexto de Modelo que permite a Claude (Desktop o claude.ai) leer tus entrenamientos, diseñar nuevas rutinas, guardarlas en tu biblioteca de Hevy y analizar tus tendencias de entrenamiento; el mismo tipo de acceso que obtienen los usuarios de ChatGPT mediante la integración oficial de Hevy.

You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
      I've trained least over the last 30 days, and save it in a folder called
      'Hypertrophy Block 1'."

Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
        ✓ created folder "Hypertrophy Block 1"
        ✓ resolved 22 exercises against Hevy's library
        ✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
        Open the Hevy app to start any of them.

Qué puedes pedirle a Claude que haga

• Mirar atrás — "Muéstrame mis últimos 10 entrenamientos y dime qué grupos musculares he estado descuidando."

• Planificar — "Basado en mi historial de press de banca, ¿cuál es una buena serie pesada para mañana?"

• Crear rutinas — "Créame una rutina de hipertrofia de 4 días dividida en torso/pierna y guárdala."

• Editar rutinas — "En el 'Día de Empuje A', cambia el press de hombros con mancuernas por un press militar con barra, 4 series de 5."

• Analizar — "Estima mi 1RM en los levantamientos principales y grafica la progresión de sentadillas en los últimos 90 días."

Requisitos

• Una suscripción a Hevy PRO (la API para desarrolladores la requiere).

• Tu clave de API de Hevy: consíguela en https://hevy.com/settings?developer.

• Python 3.11+ o Docker.

• Claude Desktop, o un espacio de trabajo en claude.ai que admita conectores personalizados.

Inicio rápido — Claude Desktop (5 minutos)

1. Instalación

# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp

# Or with pipx:
pipx install hevy-mcp

# Or with plain pip:
python -m pip install hevy-mcp

2. Añadir a Claude Desktop

Abre el archivo de configuración de Claude Desktop:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• Linux — ~/.config/Claude/claude_desktop_config.json

Añade la entrada hevy bajo mcpServers (crea el archivo si no existe):

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_paste_your_key_here"
      }
    }
  }
}

Si hevy-mcp no está en tu PATH (a veces las instalaciones de uv-tool no son detectadas por el lanzador de Claude Desktop), usa la ruta absoluta que obtienes con which hevy-mcp; por ejemplo, /Users/tu_usuario/.local/bin/hevy-mcp.

3. Reiniciar Claude Desktop

Cierra completamente la aplicación (⌘Q en macOS) y vuelve a abrirla. Deberías ver un indicador de herramientas que muestra que el servidor hevy está conectado.

4. Pruébalo

"Usa la herramienta hevy para obtener mis últimos 3 entrenamientos y resumirlos."

Si Claude muestra tus entrenamientos reales, ya está. 🎉

Alternativa — claude.ai (conector remoto)

Si usas claude.ai en el navegador en lugar de Claude Desktop, ejecuta hevy-mcp como un servicio HTTP y añádelo como un conector personalizado.

1. Ejecuta el servidor en algún lugar con HTTPS

La ruta más sencilla es Docker en Fly.io / Render / Railway:

docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcp

O directamente con la CLI:

hevy-mcp --http --host 0.0.0.0 --port 8000

El endpoint de MCP está en /mcp.

2. Añádelo como conector personalizado

En claude.ai, ve a Settings → Connectors → Add custom connector y usa tu URL HTTPS pública terminada en /mcp (ej. https://hevy-mcp.fly.dev/mcp).

Nota para múltiples usuarios

Si varios usuarios van a compartir el mismo despliegue, no incluyas HEVY_API_KEY en las variables de entorno del contenedor; en su lugar, envíala como una cabecera por solicitud. El servidor lee X-Hevy-Api-Key si está presente y, si no, recurre a la variable de entorno. Un pequeño proxy inverso que inyecte la autenticación (Cloudflare Worker, Nginx) frente al servidor es el patrón habitual.

Qué puede hacer (lista completa de herramientas)

Detalles técnicos:

• Caché inteligente — la biblioteca de ejercicios se obtiene una vez y se almacena en caché durante 24 horas; la búsqueda difusa se ejecuta en memoria.

• Consciente de los límites de tasa — reduce la velocidad ante errores 429 y respeta Retry-After.

• Escrituras idempotentes — crear una rutina con un título duplicado en la misma carpeta pide a Claude que confirme antes de duplicar.

• Errores amigables para LLM — cada error devuelve { error, hint }. La pista sugiere la siguiente llamada a herramienta concreta.

• Nunca registra tu clave de API.

Solución de problemas

Causa más común: el command en claude_desktop_config.json no está en el PATH del lanzador. Reemplaza "command": "hevy-mcp" con la ruta absoluta obtenida mediante which hevy-mcp (o where hevy-mcp en Windows). Reinicia Claude Desktop.

• Comprueba que pegaste la clave en el bloque env (no en el bloque args).

• Confirma que tu suscripción a Hevy PRO está activa.

• Regenera tu clave en https://hevy.com/settings?developer e inténtalo de nuevo.

search_exercise_templates es difusa pero no mágica. Si Claude elige el ejercicio incorrecto, pídele que "busque de nuevo con un nombre más específico" o pasa un filtro de equipment (ej. "barbell").

La biblioteca de ejercicios se obtiene en la primera búsqueda (una sola vez, ~200ms). Cada llamada posterior utiliza la caché en memoria. La caché dura 24 horas.

Desarrollo

git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev          # creates .venv and installs deps
pytest -q                    # offline tests (no real API needed)

# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py

# Stdio (Claude Desktop):
hevy-mcp

# HTTP (claude.ai):
hevy-mcp --http --port 8000

Consulta CONTRIBUTING.md para la versión extendida.

Estructura del proyecto

hevy-mcp/
├── src/hevy_mcp/
│   ├── server.py        # transport bootstrap (stdio + streamable-http)
│   ├── hevy_client.py   # async httpx client w/ retries & error mapping
│   ├── schemas.py       # Pydantic models
│   ├── cache.py         # 24-hour TTL cache
│   ├── errors.py        # HevyApiError + tool_guard
│   ├── formatters.py    # JSON → readable text
│   └── tools/           # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── Dockerfile

Lanzamientos

Consulta CHANGELOG.md. Las versiones etiquetadas se publican automáticamente en PyPI.

Licencia

MIT.

Agradecimientos

El diseño de este proyecto debe ideas a dos implementaciones comunitarias anteriores: chrisdoc/hevy-mcp (TypeScript) y SrdjanCodes/hevy-mcp (Python). No es un fork, pero vale la pena echarle un vistazo si buscas un lenguaje diferente o una combinación de funciones distinta.

hevy-mcp es un proyecto comunitario y no está afiliado ni respaldado por Hevy.