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)?".

Related MCP server: Garmin MCP Server

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) — la más sencilla:

  pip install dkwtmcp
  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.

  Para actualizar a la última versión: pip install --upgrade dkwtmcp.

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

* 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?"

Nutrición (orientación general, ver SECURITY.md)

• "Créame el perfil nutricional." (nutrition_setup_profile)

• "¿Qué debería comer hoy?" / "Hoy tengo salida larga, ¿cómo lo enfoco?" (nutrition_guidance)

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.

Los tres flujos del día a día

Brief de la mañana — fitness_daily_brief

"Dame el brief de hoy."

El vistazo antes de decidir si entrenas y cómo:

• Recuperación de anoche: sueño, HRV y FC en reposo. Se fija en la noche de hoy; si el reloj aún no ha sincronizado devuelve null, nunca la noche anterior disfrazada de anoche.

• Ayer y lo que llevas hoy: actividades de Garmin más entrenos del Apple Watch.

• Planificado para hoy, por este orden: lo ya entrenado → lo programado en Garmin → el plan semanal local (fitness_set_week_plan) → tu calendario habitual.

Cuadro de mando — fitness_dashboard

"Genérame el cuadro de mando."

Rellena una plantilla HTML con tus datos y devuelve la ruta del archivo. Se genera en segundos (frente a los minutos que tarda si le pides a Claude que dibuje el HTML desde cero en la conversación).

• Dónde queda: dashboard/cuadro_mando.html en el proyecto; si esa ruta no existe o no es escribible (por ejemplo con el binario o instalado por pip), va a ~/.dkwtmcp/dashboard/. Puedes forzar otra con output_path.

• Qué incluye: PMC (forma/fatiga/frescura con CTL, ATL y TSB), ACWR, carga semanal por sRPE, reparto por zonas de FC y composición corporal.

• Modos (focus): completo (por defecto), entrenos (oculta el bloque de peso y composición) y recomp (lo destaca). Basta con decirlo en lenguaje natural: "el cuadro de mando, solo entrenos".

• La carga usa sRPE (RPE × minutos), que sirve igual para fuerza y para e-bike. Puntúa las sesiones con fitness_log_rpe para que el PMC sea fiel.

Perfil nutricional — nutrition_setup_profile → nutrition_guidance

"Créame el perfil nutricional." y luego "¿qué debería comer hoy?"

El alta es una entrevista guiada que empieza por el cribado de salud y solo después pregunta objetivo, patrón alimentario, alergias, horarios y entrenamiento. Se previsualiza (dry_run=true) antes de guardar en ~/.dkwtmcp/nutrition/profile.json.

• Solo para personas adultas. Por debajo de 18 años no da pautas y deriva a pediatría o a un dietista-nutricionista: en crecimiento las necesidades son otras y es la etapa de mayor riesgo de trastorno alimentario.

• Derivación en dos niveles. Ciertas condiciones (enfermedad renal, diabetes, anticoagulantes, TCA, embarazo, lactancia y otras) bloquean las pautas y derivan a un profesional; otras (hipertensión leve, colesterol, SOP, tiroides controlado…) las permiten con un aviso reforzado. Si mencionas una condición nueva en la conversación, pásala en condiciones_hoy y se vuelve a comprobar.

• Solo patrones con respaldo científico: mediterráneo, comida real, DASH, nórdico y flexitariano, con modificadores (baja en hidratos moderada, vegetariano, vegano, ayuno intermitente moderado). Los estilos sin aval (keto estricta, carnívora, detox, alcalina, ayuno prolongado…) se reconducen al equivalente razonable en vez de aplicarse.

• Qué devuelve nutrition_guidance: rango de proteína (con el porqué), estrategia de hidratos según el tipo de día, mínimo de grasa, timing pre/intra/post y principios de calidad. El tipo de día se deduce con la misma prioridad que el brief y se expone en tipo_dia_detectado_por, así que sabes si es un hecho o una previsión.

• Lo que nunca hace: calcular calorías, prohibir alimentos, proponer compensar excesos con restricción o ejercicio extra, ni aceptar objetivos por debajo de un IMC saludable.

Es orientación general de estilo de vida, no asesoramiento médico ni nutricional individualizado. Ver SECURITY.md.

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. Trae Garmin, el cuadro de mando y la nutrición pública (las tres nutrition_*); Apple queda desactivado, y el módulo de nutrición personal no se incluye nunca (--exclude-module). Si hace falta configurar algo, se pasa por el bloque env de la config de Claude Desktop (ver packaging/claude_desktop_config.companero.json).

• Cada persona genera su propio perfil nutricional en su ordenador (~/.dkwtmcp/nutrition/profile.json); no viaja dentro del binario.

• 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.