DkwtMCP

Servidor MCP local que conecta Claude Desktop con tus datos de Garmin y Apple Health, para leer tu entrenamiento y recuperación, estimar tus zonas de frecuencia cardíaca y de ritmo, analizar tu rendimiento y crear/programar entrenos estructurados — todo desde una conversación con Claude. Sirve tanto para ciclismo como para running.

Proyecto personal del equipo DkwtMCP. Inspirado en FitMCP, pero de uso local: tus credenciales y datos se quedan en tu ordenador, sin servidor ni suscripciones.

---

Qué hace

• Garmin — entreno y actividades: lee tus actividades y su detalle (con splits por km), estima tus zonas de FC y tus zonas de ritmo, y crea y programa entrenos estructurados por zonas de FC o por ritmo en tu calendario de Garmin.
• Garmin — rendimiento y carga: predicciones de carrera (5K/10K/media/maratón), récords personales, VO2max y edad fitness, y estado de entrenamiento con carga aguda/crónica.
• Apple Health (vía Apple Watch): datos de salud y recuperación (sueño, HRV, FC en reposo, pasos, energía) y todos tus entrenos del Apple Watch (fuerza, caminata, remo, ciclismo indoor, etc.).
• Transversal: cruza lo planificado (Garmin) con lo ejecutado y calcula tu adherencia al plan.

La gracia es que Garmin y Apple no se hablan entre ellos, pero aquí conviven en la misma conversación: puedes preguntar "¿cómo dormí (Apple) y qué entreno me toca hoy (Garmin)?".

---

Avisos importantes

• Garmin usa la librería no oficial python-garminconnect. Funciona muy bien pero es frágil ante cambios de Garmin; la versión está fijada en requirements.txt. Es para uso personal.
• Apple Health no tiene API en la nube: los datos se obtienen exportando desde el iPhone (ver más abajo). Es solo lectura.
• Este software se ofrece "tal cual", sin garantías. Úsalo con tu propia cuenta y bajo tu responsabilidad.

---

Requisitos

• macOS (probado) o Linux. Windows debería funcionar con ajustes de rutas.
• Claude Desktop.
• Una cuenta de Garmin Connect.
• Python 3.10 o superior — solo para la instalación desde el código (opción B). Con el binario (opción A) no necesitas Python.
• (Opcional) Un Apple Watch + la app Health Auto Export para los datos de recuperación/fuerza.
• Node.js solo si quieres probar con el MCP Inspector (opcional).

---

Instalación

Hay dos formas, según tu perfil:

• A) Sin conocimientos técnicos (Mac, sin Python): usa el binario ya compilado. Solo tienes que colocar una carpeta, iniciar sesión en Garmin una vez y pegar una línea en Claude Desktop. Sigue la guía paso a paso con capturas: packaging/GUIA_INSTALACION.pdf. (El binario dkwtmcp hay que compilarlo en un Mac una vez con packaging/build_mac.sh, o pedírselo a quien te comparta el proyecto.)
• B) Desde el código (desarrolladores, con Python): sigue los pasos de abajo.
• C) Con pip, en una línea (si ya tienes Python y solo quieres usarlo):

  pip install git+https://github.com/bynoe17/DkwtMCP.git
  dkwtmcp login     # login de Garmin, una vez
  

  Esto instala el comando dkwtmcp (servidor MCP) y dkwtmcp login. En la config de Claude Desktop pon como command la ruta que te devuelva which dkwtmcp. Nota: por esta vía no hay .env del proyecto, así que los ajustes se pasan en el bloque env de la config.

Instalación desde el código (opción B)

git clone <URL-de-tu-repo> DkwtMCP
cd DkwtMCP

python3 -m venv .venv
source .venv/bin/activate           # en Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env                 # y rellena tus valores (ver abajo)

Configuración (.env)

Edita .env:

ENABLE_GARMIN=true
ENABLE_APPLE=false                   # ponlo a true si usas Apple Watch

GARMIN_EMAIL=tu_email@ejemplo.com
GARMIN_PASSWORD=tu_contraseña

APPLE_EXPORT_DIR=                     # ruta a tu carpeta de exports de Apple (ver sección Apple)

Tu .env nunca se sube a git (está en .gitignore).

---

Login de Garmin (una sola vez)

El servidor no hace login interactivo (se colgaría pidiendo el código 2FA), así que se generan los tokens una vez con un script:

python scripts/garmin_login.py

Te pedirá tu email, contraseña y, si tienes verificación en dos pasos, el código 2FA. Los tokens quedan guardados en ~/.dkwtmcp/garmin/ y se reutilizan en cada arranque. Solo hay que repetirlo si caducan.

Nota: Garmin limita los intentos de login por IP. Si ves un error 429, espera 30–60 minutos (o cambia de red, p. ej. el punto de acceso del móvil) y reintenta.

---

Sincronización con Apple Health

Apple Health no se puede sincronizar hacia Garmin ni tiene API en la nube. La forma práctica de traer tus datos del Apple Watch (sueño, HRV, FC en reposo, fuerza) es la app Health Auto Export – JSON+CSV (App Store), que exporta automáticamente a una carpeta.

1. Instala y configura Health Auto Export

1. Instala Health Auto Export – JSON+CSV en el iPhone.
2. Crea una automatización (o exportación) con estas opciones:
   • Formato: JSON.
   • Destino: iCloud Drive (así los archivos aparecen también en tu Mac).
   • Frecuencia: por ejemplo, diaria.
3. Métricas de salud — asegúrate de incluir al menos: Sleep Analysis, Heart Rate Variability, Resting Heart Rate, Heart Rate, Steps, Active Energy.
4. Entrenos (Workouts) — es una categoría aparte. Si quieres ver tus sesiones de fuerza, añade también una exportación de Workouts en JSON al mismo sitio.

Puedes usar dos automatizaciones (una de métricas y otra de workouts) apuntando a subcarpetas dentro de una carpeta común; el MCP las lee de forma recursiva.

Sobre el sueño: el MCP entiende tanto el formato agregado (en minutos) como el detallado por segmentos, y calcula fases (Profundo, Esencial/Core, REM), Vigilia y Tiempo en la cama para que coincidan con la app Salud del iPhone.

2. Apunta APPLE_EXPORT_DIR a la carpeta

Health Auto Export guarda en su propia carpeta de iCloud, cuya ruta en el Mac es del tipo:

/Users/TU_USUARIO/Library/Mobile Documents/iCloud~com~ifunography~HealthExport/Documents

Pon esa carpeta (la que contiene tus subcarpetas de export) en APPLE_EXPORT_DIR, y ENABLE_APPLE=true. El escaneo es recursivo, así que basta con apuntar a la carpeta padre.

iCloud: si tienes activado "Optimizar almacenamiento del Mac", los archivos pueden estar solo en la nube. Haz clic derecho en la carpeta → Descargar ahora para que estén en local.

3. Importa

Los datos de Apple se importan bajo demanda. En una conversación de Claude di "importa mi Apple Salud" (ejecuta apple_import_export), que guarda una base local (SQLite) en ~/.dkwtmcp/apple/.

El import es incremental por defecto: solo procesa los archivos nuevos o cambiados desde la última vez (rápido, ideal para la automatización diaria de Health Auto Export). Si alguna vez quieres reconstruir desde cero, pide un import con full_rebuild.

---

Perfil de usuario (opcional)

Para no repetirle a Claude tu FC máxima o tu ritmo umbral cada vez, guárdalos en el .env:

USER_MAX_HR=179
USER_THRESHOLD_PACE=4:20
USER_RESTING_HR=
USER_AGE=

Las herramientas de zonas (garmin_hr_zones, garmin_pace_zones) usan estos valores por defecto cuando no se los indicas. Consulta lo configurado con fitness_profile.

---

Conectar a Claude Desktop

1. En Claude Desktop: Ajustes → Developer → Edit Config (abre claude_desktop_config.json).
2. Añade el bloque de mcpServers (ver claude_desktop_config.example.json), ajustando las rutas a tu instalación:

{
  "mcpServers": {
    "DkwtMCP": {
      "command": "/ruta/a/DkwtMCP/.venv/bin/python",
      "args": ["-m", "dkwt_mcp.server"],
      "cwd": "/ruta/a/DkwtMCP/src",
      "env": { "PYTHONPATH": "/ruta/a/DkwtMCP/src" }
    }
  }
}

3. Cierra Claude Desktop del todo (Cmd+Q) y reábrelo. Deberías ver DkwtMCP en el menú de herramientas.

Usa el Python del entorno virtual (.venv/bin/python), no el del sistema; si no, no encontrará las dependencias.

Consejo: instrucciones del proyecto

Para que Claude elija bien las herramientas, en tu Proyecto de Claude añade instrucciones tipo: "la recuperación (sueño, HRV, FC reposo) viene de Apple; las actividades, entrenos, zonas (FC y ritmo), rendimiento y carga, de Garmin". Y si eres corredor, indícalo ("entreno running, prográmame por ritmo con sport=running") para que use ritmo en vez de zonas de FC.

---

Herramientas disponibles

Herramienta	Plataforma	Qué hace
garmin_daily_readiness	Garmin	Recuperación del día (readiness, HRV, sueño, FC reposo, estrés, Body Battery)*
garmin_get_activities	Garmin	Últimas actividades con métricas
garmin_get_activity	Garmin	Detalle de una actividad
garmin_sleep / garmin_hrv	Garmin	Desglose de sueño / HRV nocturna*
garmin_hr_zones	Garmin	Estima tus zonas de FC (Karvonen o %FCmax), filtrando lecturas imposibles
garmin_pace_zones	Garmin	Estima zonas de ritmo (running) a partir del ritmo umbral
garmin_activity_splits	Garmin	Parciales (splits) de una actividad con ritmo por km y FC
garmin_race_predictions	Garmin	Predicciones de tiempo 5K / 10K / media / maratón
garmin_personal_records	Garmin	Récords personales (mejores marcas)
garmin_fitness_metrics	Garmin	VO2max (correr y ciclismo) y edad fitness
garmin_training_status	Garmin	Estado de entrenamiento, carga aguda/crónica, VO2max y endurance score
garmin_schedule_workout	Garmin	Crea y programa entrenos estructurados: pasos por tiempo o distancia, series con repeticiones, y objetivos de FC, ritmo o potencia (previsualización por defecto)
garmin_plan_week	Garmin	Programa varias sesiones de golpe (el plan de la semana o del bloque)
garmin_list_workouts / garmin_delete_workout	Garmin	Listar / borrar entrenos guardados
fitness_planned_vs_actual	Transversal	Compara plan (entrenos programados) vs. ejecutado y calcula adherencia
fitness_weekly_summary	Transversal	Resumen del periodo: km/horas (Garmin) + sueño/HRV/reposo/pasos (Apple)
fitness_recovery_vs_training	Transversal	Cruce día a día de entreno vs. recuperación (HRV, sueño, FC reposo)
garmin_add_body_composition	Garmin	Registra peso y composición corporal (para básculas que no sincronizan)
fitness_body_composition	Transversal	Evolución de peso, % grasa y músculo (Garmin + Apple) con tendencia
fitness_daily_brief	Transversal	Brief de la mañana: recuperación de anoche + ayer + plan de hoy
fitness_dashboard	Transversal	Genera un cuadro de mando en HTML interactivo: PMC (forma/fatiga/frescura), ACWR, zonas de FC, carga semanal y composición corporal
fitness_log_rpe	Transversal	Puntúa el esfuerzo de una sesión (RPE 1-10) para calcular la carga por sRPE
apple_import_export	Apple	Importa tus exports de Apple Health/Health Auto Export a una base local
apple_query_metric	Apple	Sueño (por noche), HRV, FC reposo, pasos, energía en un rango
apple_get_workouts	Apple	Entrenos del Apple Watch (fuerza, caminata, remo, etc.)
fitness_profile	Perfil	Muestra tu perfil (FCmáx, FC reposo, edad, ritmo umbral) del .env

* Las métricas de recuperación de Garmin (sueño, HRV, Body Battery…) requieren un reloj/pulsera Garmin; un ciclocomputador Edge no las registra. En ese caso usa las herramientas de Apple.

---

Ejemplos de uso

Una vez conectado, habla con Claude en lenguaje natural:

Ciclismo / general

• "Lista mis últimas 5 actividades de Garmin."
• "Estima mis zonas de frecuencia cardíaca."
• "Prográmame un 4×5 minutos en Zona 4 para el sábado (primero en previsualización)."
• "Móntame el plan de la semana que viene: rodaje Z2 el martes, series el jueves y salida larga el domingo." (garmin_plan_week)
• "¿Cumplí el plan esta semana?" (plan vs. ejecutado)

Running

• "Estima mis zonas de ritmo, mi umbral es 4:20/km."
• "Prográmame un rodaje de 40 min en ritmo fácil el domingo."
• "Un 5×1000 m a 4:20-4:30 con 2 min de recuperación, para el martes." (series por distancia, agrupadas como repeticiones)
• "¿Cómo dosifiqué mi última carrera? Enséñame los splits."
• "¿Qué tiempo predice Garmin para mi media maratón? ¿Y mis récords?"
• "¿Cómo va mi estado de entrenamiento y mi carga aguda/crónica?"

Recuperación y fuerza (Apple)

• "¿Cómo dormí anoche?"
• "¿Cuántos entrenos de fuerza hice en junio y cuánto sumaron?"

Resúmenes y correlaciones (Garmin + Apple)

• "Hazme el resumen de esta semana." (fitness_weekly_summary)
• "¿Mi HRV baja los días que entreno duro?" / "¿Duermo peor tras la fuerza?" (fitness_recovery_vs_training)
• "Apunta mi medición de hoy: 89 kg, 38% de grasa, 30 kg de músculo." (garmin_add_body_composition)
• "¿Cómo va mi peso y mi % de grasa estos 3 meses?" (fitness_body_composition)
• "Dame el brief de hoy: ¿cómo vengo y qué me toca?" (fitness_daily_brief)
• "Genérame el cuadro de mando." (fitness_dashboard — crea el HTML en dashboard/ en segundos)

Seguridad en escritura

Las herramientas que escriben en Garmin llevan confirmación: garmin_schedule_workout usa dry_run (por defecto solo previsualiza) y garmin_delete_workout requiere confirm=true.

---

Probar sin Claude Desktop (opcional)

Con el MCP Inspector:

cd src
npx @modelcontextprotocol/inspector python -m dkwt_mcp.server

---

Compartir con otra persona

En packaging/ hay lo necesario para generar un binario de macOS autocontenido (con PyInstaller) que no requiere Python en el ordenador de destino, pensado para alguien sin conocimientos técnicos. Cada persona usa su propia cuenta de Garmin. Ver packaging/GUIA_INSTALACION.pdf.

Genéralo con bash packaging/build_mac.sh (resultado en dist/dkwtmcp). Notas:

• El binario no lee el .env del proyecto: viene con Garmin activado y Apple/nutrición desactivados. Si hace falta configurar algo, se pasa por el bloque env de la config de Claude Desktop (ver packaging/claude_desktop_config.companero.json).
• Hay que recompilarlo cada vez que quieras que la otra persona reciba mejoras: no se actualiza solo.
• Para comprobar que un binario recién hecho responde, sin depender de otras herramientas:

  { printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fitness_profile","arguments":{"params":{}}}}' ; sleep 8; } | ./dist/dkwtmcp 2>/dev/null
  

---

Solución de problemas

DkwtMCP no aparece en Claude Desktop. Revisa que en claude_desktop_config.json la ruta a Python sea la del entorno virtual (.venv/bin/python) y que cwd/PYTHONPATH apunten a src. Cierra Claude del todo (Cmd+Q) y reábrelo; recargar la ventana no basta.

Cambié el código y no veo el cambio. El servidor MCP se carga al arrancar Claude Desktop. Tras editar código, cierra y reabre Claude Desktop. Si tocaste datos de Apple, vuelve a importar ("importa mi Apple Salud").

Login de Garmin: error 429. Garmin limita los intentos por IP. Espera 30–60 minutos sin reintentar, o cambia de red (p. ej. el punto de acceso del móvil) y repite el login.

Login de Garmin falla / dejó de funcionar. Los tokens pueden caducar, o Garmin puede haber cambiado su sistema (la librería es no oficial). Vuelve a ejecutar python scripts/garmin_login.py. Si sigue fallando, comprueba si hay una versión nueva de garminconnect.

Las métricas de recuperación de Garmin (sueño, HRV, Body Battery) salen vacías. Esas las mide un reloj/pulsera Garmin en la muñeca; un ciclocomputador Edge no las registra. Si llevas Apple Watch, usa las herramientas de Apple para la recuperación.

Apple: "no hay datos importados". Ejecuta primero apple_import_export ("importa mi Apple Salud"). El import borra y reconstruye la base cada vez.

Apple: no encuentra la carpeta de exports. Health Auto Export guarda en su propia carpeta de iCloud (.../iCloud~com~ifunography~HealthExport/Documents). Apunta APPLE_EXPORT_DIR ahí. Si usas iCloud con "Optimizar almacenamiento", haz clic derecho en la carpeta → Descargar ahora.

Herramientas de running (predicciones, récords, estado) salen con campos vacíos. Requieren un reloj Garmin con esos datos calculados y actividades recientes. Si algún campo sale null pese a tenerlo en Garmin, es cosa del parseo: ábrelo con response_format: "json" y repórtalo.

---

Preguntas frecuentes (FAQ)

¿Necesito saber programar o tener Python? Para la vía del binario (opción A) no. Para instalar desde el código (opción B) sí necesitas Python.

¿Funciona con el plan gratuito de Claude? Sí. Los MCP locales por archivo de configuración funcionan en Claude Desktop, también en el plan Free.

¿Se suben mis datos a algún sitio? No. Todo es local: tus credenciales van en .env (nunca al repo) y los datos se guardan en ~/.dkwtmcp/ de tu ordenador. No hay servidor.

¿Puedo compartirlo? ¿Y usarlo varias personas? Sí. El código se comparte; cada persona usa su propia cuenta de Garmin (su propio login y tokens).

¿Sirve para ciclismo y para running? Para ambos. Ciclismo por zonas de FC/potencia; running por zonas de ritmo, con análisis de rendimiento y carga.

¿Soporta Strava? No por ahora. Sus términos (2025) prohíben usar sus datos en IA, así que se retiró del alcance.

¿Por qué puede dejar de funcionar Garmin de repente? Usa una librería no oficial; si Garmin cambia su sistema de acceso, puede romperse hasta que la librería se actualice. Es un riesgo asumido de un proyecto personal.

¿Cada cuánto tengo que importar los datos de Apple? Cuando quieras refrescar. Con una automatización de Health Auto Export que deje los archivos en la carpeta, basta con volver a decir "importa mi Apple Salud".

¿Funciona en Windows? Debería, ajustando rutas. Está probado en macOS.

---

Estructura del proyecto

DkwtMCP/
├── src/dkwt_mcp/
│   ├── app.py              # instancia FastMCP
│   ├── server.py           # entrypoint (stdio)
│   ├── cli.py / login.py   # login de Garmin y arranque
│   ├── config.py           # configuración desde .env
│   ├── common.py           # utilidades (errores, formato)
│   └── providers/
│       ├── garmin.py       # herramientas garmin_*
│       ├── apple.py        # herramientas apple_*
│       └── fitness.py      # herramienta transversal fitness_*
├── scripts/garmin_login.py
├── packaging/              # binario y guía para compartir
├── requirements.txt
├── .env.example
└── claude_desktop_config.example.json

---

Desarrollo y tests

El proyecto incluye una batería de tests (funciones puras de parseo y construcción de entrenos) que se ejecutan en cada push mediante GitHub Actions.

pip install -r requirements-dev.txt
pytest -q

---

Contribuir

Las aportaciones son bienvenidas: lee CONTRIBUTING.md para el entorno de desarrollo y las convenciones del proyecto.

Importante: al abrir un issue no incluyas credenciales, tokens ni datos de salud reales. Ver SECURITY.md para cómo se tratan tus datos y cómo reportar un problema de seguridad.

---

Licencia

Publicado bajo licencia MIT — ver LICENSE. Puedes usarlo, modificarlo y distribuirlo libremente, conservando el aviso de copyright (el crédito a la autora).

Cómo citar

Si usas este proyecto, cítalo por favor. GitHub mostrará un botón "Cite this repository" gracias a CITATION.cff. En resumen:

Infantes, N. (2026). DkwtMCP – MCP local para Garmin y Apple Health.

---

Aviso legal

Proyecto personal, sin relación con Garmin ni Apple. Usa una librería no oficial para Garmin; su funcionamiento puede romperse si Garmin cambia su sistema. No hay garantía de ningún tipo. Tú eres responsable del uso que hagas de tus propias cuentas y datos.