intervals-icu-mcp

Servidor MCP de Intervals.icu

Un servidor de Model Context Protocol (MCP) para la integración con Intervals.icu. Accede a tus datos de entrenamiento, métricas de bienestar y análisis de rendimiento a través de Claude, ChatGPT y otros LLMs.

Originalmente basado en eddmann/intervals-icu-mcp (licencia MIT). Este proyecto es una continuación independiente con correcciones de errores significativas y nuevas funciones; consulta CHANGELOG.md para más detalles.

Resumen

62 herramientas que abarcan actividades, análisis de actividades, mensajes de actividades, perfil del atleta, bienestar, eventos/calendario, curvas de rendimiento, biblioteca de entrenamientos, equipamiento, configuración deportiva y elementos personalizados — además de 4 Recursos MCP (perfil del atleta, sintaxis de entrenamientos, categorías de eventos, esquemas de elementos personalizados) y 7 Prompts MCP (análisis de entrenamiento, verificación de recuperación, planificación semanal y más). Consulta Herramientas disponibles para el desglose por categoría.

Inicio rápido

O para Claude Desktop, en 30 segundos:

1. Obtén tu clave de API e ID de atleta
2. Añade esto a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

3. Reinicia Claude y pregunta "Muéstrame mis actividades de los últimos 7 días."

¿Prefieres Claude Code, Cursor o ChatGPT? Consulta Configuración del cliente. ¿Quieres ejecutarlo desde el código fuente o con Docker? Consulta Instalación y configuración.

Requisitos previos

Instala uv — gestiona Python, dependencias y ejecución en una sola herramienta. brew install uv en macOS/Linux, o powershell -c "irm https://astral.sh/uv/install.ps1 | iex" en Windows. A partir de ahí, uvx descarga Python y el paquete automáticamente. Docker también es compatible como alternativa.

Configuración de la clave API de Intervals.icu

Antes de la instalación, obtén tu clave API de Intervals.icu:

1. Ve a https://intervals.icu/settings → Desarrollador → Crear clave API.
2. Copia la clave y anota tu ID de atleta desde la URL de tu perfil (formato: i123456).

Instalación y configuración

No necesitas instalar nada por separado si usas la configuración recomendada. uvx (que se incluye con uv) descarga y almacena en caché automáticamente el paquete intervals-icu-mcp la primera vez que tu cliente MCP lo lanza — solo pega el fragmento de configuración de Configuración del cliente en tu cliente y listo.

git clone https://github.com/hhopke/intervals-icu-mcp.git
cd intervals-icu-mcp
uv sync
uv run intervals-icu-mcp-auth  # interactive credential setup; or create .env manually:
#   INTERVALS_ICU_API_KEY=your_api_key_here
#   INTERVALS_ICU_ATHLETE_ID=i123456

docker build -t intervals-icu-mcp .

# Interactive credential setup (creates intervals-icu-mcp.env in the current directory):
touch intervals-icu-mcp.env  # pre-create the file so Docker mounts it as a file, not a dir
docker run -it --rm \
  -v "$(pwd)/intervals-icu-mcp.env:/app/.env" \
  --entrypoint= intervals-icu-mcp:latest \
  python -m intervals_icu_mcp.scripts.setup_auth

Configuración del cliente

El servidor habla MCP sobre stdio y funciona con cualquier cliente compatible. Haz clic en un cliente para expandirlo. Si seguiste el Inicio rápido (uvx), usa el primer bloque de configuración; si usaste la alternativa desde el código fuente o Docker anterior, usa la variante correspondiente dentro del mismo bloque plegable.

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/intervals-icu-mcp", "intervals-icu-mcp"]
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/ABSOLUTE/PATH/TO/intervals-icu-mcp.env:/app/.env", "intervals-icu-mcp:latest"]
    }
  }
}

claude mcp add intervals-icu --scope user \
  --env INTERVALS_ICU_API_KEY=your-key \
  --env INTERVALS_ICU_ATHLETE_ID=i123456 \
  -- uvx intervals-icu-mcp

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

Uso

Pide a Claude que interactúe con tus datos de Intervals.icu en lenguaje natural. Algunos prompts iniciales:

"Show me my activities from the last 30 days"
"Am I overtraining? Check my CTL, ATL, and TSB"
"How's my recovery this week? Show HRV and sleep trends"
"Create a sweet spot cycling workout for tomorrow"
"What's my 20-minute power and FTP?"

Para el catálogo completo de prompts de ejemplo por categoría, consulta docs/examples.md.

Herramientas disponibles

62 herramientas, 4 recursos y 7 plantillas de prompts. Resumen en una línea a continuación — referencia completa en docs/tools.md.

Modo de seguridad para eliminación

Las herramientas destructivas están controladas por la variable de entorno opcional INTERVALS_ICU_DELETE_MODE (safe / full / none, valor predeterminado safe) — una protección del lado del servidor fuera del alcance del modelo, por lo que las herramientas no registradas no pueden invocarse. Consulta docs/tools.md para la tabla completa de modos, el formato de respuesta y la justificación del búfer de zona horaria.

Implementación remota (HTTP / SSE)

El servidor se ejecuta sobre stdio de forma predeterminada — el transporte adecuado para clientes locales como Claude Desktop, Claude Code y Cursor. Los transportes HTTP y SSE están disponibles para uso remoto o alojado.

⚠️ MCP no tiene autenticación integrada — nunca expongas un servidor en modo HTTP a una red no confiable sin un túnel (Tailscale, Cloudflare Tunnel) o un proxy inverso con autenticación.

Consulta docs/remote-deployment.md para las opciones de transporte y el modelo de seguridad completo.

Documentación

• Prompts de ejemplo — catálogo completo de prompts en lenguaje natural por categoría
• Referencia de herramientas — inventario completo de herramientas, recursos y prompts
• Resumen de arquitectura — cómo encajan el servidor, el middleware, el cliente y las herramientas
• Implementación remota (HTTP/SSE) — transportes, opciones y el modelo de seguridad para configuraciones alojadas/remotas
• Guía de pruebas — convenciones para pytest + respx, fixtures y ejecución de la suite
• Registro de cambios — historial de versiones
• Añadir una nueva herramienta — flujo de trabajo paso a paso para colaboradores

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Antes de abrir una PR, ejecuta make can-release localmente para coincidir con lo que exige CI (ruff, pyright, pytest). Para nuevas herramientas, sigue el patrón en .claude/skills/add-tool/SKILL.md y añade un archivo de prueba con respx simulado junto a la implementación.

Licencia

Licencia MIT — consulta el archivo LICENSE para más detalles.

Aviso legal

Este proyecto no está afiliado, respaldado ni patrocinado por Intervals.icu. Todos los nombres de productos, logotipos y marcas son propiedad de sus respectivos dueños.