Intervals.icu

Se conecta a la API de Intervals.icu para recuperar actividades, eventos y datos de bienestar.

Documentación

Servidor MCP de Intervals.icu

Servidor de Protocolo de Contexto de Modelo (MCP) para conectar Claude y ChatGPT con la API de Intervals.icu. Proporciona herramientas para autenticación y recuperación de datos de actividades, eventos, datos de bienestar, curvas de potencia y elementos personalizados.

Si encuentras útil el servidor de Protocolo de Contexto de Modelo (MCP), considera apoyar su desarrollo continuo con una donación.

Requisitos

Python 3.12 o superior
SDK de Python de Protocolo de Contexto de Modelo (MCP)
httpx
python-dotenv

Configuración

1. Instalar uv (recomendado)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Después de la instalación, encuentra la ruta completa a uv — la necesitarás más adelante al configurar Claude Desktop:

where.exe uv
# Example output: C:\Users\<USERNAME>\.local\bin\uv.exe

2. Clonar este repositorio

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. Crear y activar un entorno virtual

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. Sincronizar las dependencias del proyecto

uv sync

5. Configurar las variables de entorno

Haz una copia de .env.example y nómbrala .env ejecutando el siguiente comando:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Luego edita el archivo .env y establece tu ID de atleta e clave de API de Intervals.icu:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Cómo obtener tu clave de API de Intervals.icu

Inicia sesión en tu cuenta de Intervals.icu
Ve a Configuración > API
Genera una nueva clave de API

Cómo encontrar tu ID de atleta

Tu ID de atleta generalmente es visible en la URL cuando inicias sesión en Intervals.icu. Se ve así:

https://intervals.icu/athlete/i12345/... donde i12345 es tu ID de atleta

Actualización

Este proyecto se desarrolla activamente, con nuevas funciones y correcciones añadidas regularmente. Para mantenerte actualizado, sigue estos pasos:

1. Obtén los últimos cambios de `main`

⚠️ Asegúrate de no tener cambios sin confirmar antes de ejecutar este comando.

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Actualizar las dependencias de Python

Activa tu entorno virtual y sincroniza las dependencias:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

Solución de problemas

Si Claude Desktop falla debido a cambios en la configuración, sigue estos pasos:

Elimina la entrada existente de Intervals.icu en claude_desktop_config.json.
Reconfigura Claude Desktop desde el directorio intervals-mcp-server.

macOS/Linux:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

Windows: Vuelve a añadir la entrada manualmente como se describe en la sección de configuración de Windows.

Errores comunes

spawn uv ENOENT — Claude Desktop no puede encontrar el ejecutable uv. Usa la ruta completa a uv en el campo command. Ejecuta which uv (macOS/Linux) o where.exe uv (Windows) para obtenerlo.

spawn /Users/... ENOENT en Windows — El archivo de configuración contiene una ruta de estilo macOS/Linux. Reemplázala con la ruta correcta de Windows usando barras invertidas como se describe en la sección de configuración de Windows a continuación.

Instalación desde Microsoft Store: los cambios de configuración no surten efecto — Es posible que estés editando el archivo de configuración incorrecto. Claude Desktop instalado desde Microsoft Store lee desde AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, no desde AppData\Roaming\Claude\.

Uso con Claude

1. Configurar Claude Desktop

Para usar este servidor con Claude Desktop, debes añadirlo a tu configuración de Claude Desktop.

macOS/Linux

Ejecuta lo siguiente desde el directorio intervals-mcp-server para configurar Claude Desktop:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

Si abres tu archivo de configuración de la aplicación Claude Desktop claude_desktop_config.json, debería verse así:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/Users/<USERNAME>/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/intervals-mcp-server",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Donde /path/to/ es la ruta a la carpeta de código de intervals-mcp-server en tu sistema.

Windows

El comando mcp install puede fallar en Windows debido a problemas de entorno o permisos. En su lugar, configura Claude Desktop manualmente:

Encuentra el archivo de configuración de Claude Desktop. Si Claude Desktop se instaló desde Microsoft Store, la configuración se encuentra en:
```
C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
```
Si se instaló mediante el instalador estándar, puede estar en:
```
C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json
```
Si el archivo o carpeta no existe, créalo.
Añade la siguiente entrada a claude_desktop_config.json, reemplazando los marcadores de posición con tus valores reales:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "C:\\path\\to\\intervals-mcp-server",
        "mcp",
        "run",
        "C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Usa barras invertidas dobles (\\) para todas las rutas de Windows en JSON.
Para encontrar la ruta completa a uv.exe, ejecuta where.exe uv en PowerShell.
Para encontrar la ruta completa del repositorio clonado, ejecuta pwd desde dentro de la carpeta intervals-mcp-server.

Nota para instalaciones desde Microsoft Store: Claude Desktop instalado desde Microsoft Store aísla su configuración bajo AppData\Local\Packages\.... Editar AppData\Roaming\Claude\claude_desktop_config.json no tendrá efecto — asegúrate de editar el archivo correcto.

Reinicia Claude Desktop.

2. Usar el servidor MCP con Claude

Una vez que el servidor esté en ejecución y Claude Desktop esté configurado, puedes usar las siguientes herramientas para hacer preguntas sobre tus actividades pasadas y futuras, eventos y datos de bienestar.

get_activities: Recuperar una lista de actividades
get_activity_details: Obtener información detallada de una actividad específica
get_activity_intervals: Obtener datos detallados de intervalos de una actividad específica
get_activity_streams: Obtener flujos de datos brutos (potencia, frecuencia cardíaca, etc.) de una actividad específica
get_athlete_power_curves: Obtener las mejores curvas de potencia de salida para duraciones y períodos de tiempo seleccionados
get_wellness_data: Obtener datos de bienestar
get_events: Recuperar próximos eventos (entrenamientos, carreras, etc.)
get_event_by_id: Obtener información detallada de un evento específico
add_or_update_event: Crear o actualizar un evento (entrenamiento, carrera, nota, etc.)
delete_event: Eliminar un evento específico
delete_events_by_date_range: Eliminar eventos dentro de un rango de fechas
get_custom_items: Obtener elementos personalizados (gráficos, campos personalizados, zonas, etc.) de un atleta
get_custom_item_by_id: Obtener información detallada de un elemento personalizado específico
create_custom_item: Crear un nuevo elemento personalizado para un atleta
update_custom_item: Actualizar un elemento personalizado existente
delete_custom_item: Eliminar un elemento personalizado

Uso con ChatGPT

Los conectores MCP beta de ChatGPT también pueden comunicarse con este servidor a través del transporte SSE.

Inicia el servidor en modo SSE para que exponga los endpoints /sse y /messages/:
```
export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
python src/intervals_mcp_server/server.py
```
El registro de inicio imprime las URL completas (por ejemplo, http://127.0.0.1:8765/sse). ChatGPT necesita esa URL pública, así que reenvía el puerto con una herramienta como ngrok http 8765 si no estás exponiendo el servidor directamente.
En ChatGPT, abre Configuración → Funciones → Conectores MCP personalizados y haz clic en Añadir. Completa:
- Nombre: Intervals.icu
- URL del servidor MCP: https://<your-public-host>/sse
- Autenticación: déjalo en Sin autenticación a menos que hayas protegido tu túnel.
Puedes reutilizar la misma URL de túnel ngrok http 8765 aquí; solo asegúrate de que reenvíe al host/puerto que exportaste anteriormente.
Guarda el conector y abre un nuevo chat. ChatGPT mantendrá la conexión SSE abierta y enviará solicitudes de seguimiento POST al endpoint /messages/ anunciado por el servidor. Si reinicias el servidor MCP o el túnel, vuelve a ejecutar el comando SSE y actualiza la URL del conector si cambia.

Desarrollo y pruebas

Instala las dependencias de desarrollo y ejecuta la suite de pruebas con:

uv sync --all-extras
pytest -v tests

Ejecutar el servidor localmente

Para iniciar el servidor manualmente (útil al desarrollar o probar), ejecuta:

mcp run src/intervals_mcp_server/server.py

Habilitar el registro de depuración

Para capturar los registros del servidor para depuración, envuelve el comando en un shell y redirige stderr a un archivo.

macOS/Linux — modifica tu claude_desktop_config.json así:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/Users/<USERNAME>/.local/bin/uv run --with 'mcp[cli]' --with-editable /path/to/intervals-mcp-server mcp run /path/to/intervals-mcp-server/src/intervals_mcp_server/server.py 2>> /path/to/intervals-mcp-server/mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Luego sigue el archivo de registro para ver la salida en tiempo real:

tail -f /path/to/intervals-mcp-server/mcp-server.log

Windows — modifica tu claude_desktop_config.json así:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "powershell",
      "args": [
        "-Command",
        "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe run --with 'mcp[cli]' --with-editable C:\\path\\to\\intervals-mcp-server mcp run C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py 2>> C:\\path\\to\\intervals-mcp-server\\mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Luego monitorea el archivo de registro en tiempo real usando PowerShell:

Get-Content C:\path\to\intervals-mcp-server\mcp-server.log -Wait

Licencia

La Licencia Pública General de GNU v3.0

Intervals.icu

Documentación

Servidor MCP de Intervals.icu

Requisitos

Configuración

1. Instalar uv (recomendado)

2. Clonar este repositorio

3. Crear y activar un entorno virtual

4. Sincronizar las dependencias del proyecto

5. Configurar las variables de entorno

Cómo obtener tu clave de API de Intervals.icu

Cómo encontrar tu ID de atleta

Actualización

1. Obtén los últimos cambios de `main`

2. Actualizar las dependencias de Python

Solución de problemas

Errores comunes

Uso con Claude

1. Configurar Claude Desktop

macOS/Linux

Windows

2. Usar el servidor MCP con Claude

Uso con ChatGPT

Desarrollo y pruebas

Ejecutar el servidor localmente

Habilitar el registro de depuración

Licencia

Destacado

Glama.ai

Intervals.icu

Documentación

Servidor MCP de Intervals.icu

Requisitos

Configuración

1. Instalar uv (recomendado)

2. Clonar este repositorio

3. Crear y activar un entorno virtual

4. Sincronizar las dependencias del proyecto

5. Configurar las variables de entorno

Cómo obtener tu clave de API de Intervals.icu

Cómo encontrar tu ID de atleta

Actualización

1. Obtén los últimos cambios de main

2. Actualizar las dependencias de Python

Solución de problemas

Errores comunes

Uso con Claude

1. Configurar Claude Desktop

macOS/Linux

Windows

2. Usar el servidor MCP con Claude

Uso con ChatGPT

Desarrollo y pruebas

Ejecutar el servidor localmente

Habilitar el registro de depuración

Licencia

Destacado

Glama.ai

1. Obtén los últimos cambios de `main`