Intervals.icu MCP Server

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

Si te resulta útil el servidor Model Context Protocol (MCP), considera la opción de apoyar su desarrollo continuo con una donación.

Requisitos

• Python 3.12 o superior

• Model Context Protocol (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

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 ubicación completa de 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

A continuación, edita el archivo .env y establece tu ID de atleta y la clave de API de Intervals.icu:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Obtener tu clave de API de Intervals.icu

1. Inicia sesión en tu cuenta de Intervals.icu

2. Ve a Ajustes > API

3. Genera una nueva clave de API

Encontrar tu ID de atleta

Tu ID de atleta suele ser visible en la URL cuando inicias sesión en Intervals.icu. Tiene el siguiente aspecto:

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

Actualizar

Este proyecto se desarrolla activamente, con nuevas características y correcciones añadidas con regularidad. Para mantenerte actualizado, sigue estos pasos:

1. Traer 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 errores

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

1. Elimina la entrada existente Intervals.icu en claude_desktop_config.json.

2. Vuelve a configurar 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 de 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 de Microsoft Store: los cambios de configuración no se aplican — Es posible que estés editando el archivo de configuración incorrecto. Claude Desktop instalado desde Microsoft Store lee de AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, no de AppData\Roaming\Claude\.

Uso con Claude

1. Configurar Claude Desktop

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

macOS/Linux

1. Ejecuta lo siguiente desde la carpeta intervals-mcp-server para configurar Claude:

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

2. Si abres el archivo de configuración claude_desktop_config.json de Claude Desktop, 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 intervals-mcp-server de 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:

1. Encuentra el archivo de configuración de Claude Desktop. Si Claude Desktop se instaló desde Microsoft Store, el archivo 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 que esté en:

   C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json

   Si no existen el archivo ni la carpeta, créalos.

2. Añade la siguiente entrada a claude_desktop_config.json, reemplazando los marcadores de posición por 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 dobles barras invertidas (\\) para todas las rutas de Windows en JSON.

• Para encontrar la ruta completa uv.exe, ejecuta where.exe uv en PowerShell.

• Para encontrar la ruta completa al repositorio clonado, ejecuta pwd desde la carpeta intervals-mcp-server.

Nota para instalaciones de Microsoft Store: Claude Desktop instalado desde Microsoft Store crea una zona segura para su configuración en AppData\Local\Packages\.... Editar AppData\Roaming\Claude\claude_desktop_config.json no tendrá ningún efecto; asegúrate de poseer el archivo correcto.

3. 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, eventos y datos de bienestar, pasados y futuros:

• get_activities: Recupera una lista de actividades

• get_activity_details: Obtén esta información detallada de una actividad concreta

• get_activity_intervals: Obtén datos detallados de intervalos de una actividad concreta

• get_activity_streams: Obtén los flujos de datos sin formato (potencia, frecuencia cardíaca, etc.) de una actividad concreta

• get_athlete_power_curves: Obtén las curvas de mejor potencia para duraciones y períodos de tiempo seleccionados

• get_wellness_data: Recupera datos de bienestar

• get_events: Recupera los próximos eventos (entrenamientos, carreras, etc.)

• get_event_by_id: Obtén información detallada de un evento específico

• create_or_update_event: Crea o actualiza un evento (entrenamiento, carrera, nota, etc.)

• delete_event: Elimina un evento específico

• delete_events_by_date_range: Elimina los eventos de un rango de fechas

• get_custom_items: Obtén elementos personalizados (gráficos, campos de medida, zonas, etc.) de un atleta

• get_custom_item_by_id: Obtén información detallada de un elemento personalizado concreto

• create_custom_item: Crea un nuevo elemento personalizado para un atleta

• update_custom_item: Actualiza un elemento personalizado existente

• delete_custom_item: Elimina un elemento personalizado

Uso con ChatGPT

Los conectores MCP de ChatGPT en versión beta también pueden comunicarse con este servidor mediante el transporte SSE.

1. Inicia el servidor en modo SSE para que sea visible los puntos terminales /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 muestra las direcciones completas (por ejemplo, http://127.0.0.1:8765/sse). ChatGPT necesita esa dirección pública, así que redirige el puerto con una herramienta como ngrok http 8765 si no expones el servidor directamente.

2. En ChatGPT, abre Ajustes → Funciones → Conectores MCP personalizados y haz clic en Añadir. Completa la siguiente información:

• Nombre: Intervals.icu

• URL del servidor MCP: https://<your-public-host>/sse

• Autenticación: déjalo como Sin autenticación a menos que hayas protegido tu túnel.

Puedes reutilizar la misma URL del túnel ngrock http 8765; solo asegúrate de que enruta hacia el host/puerto que has exportado anteriormente.

3. Guarda el conector y abre un chat nuevo. ChatGPT mantendrá abierta la conexión SSE y enviará solicitudes POST de seguimiento al endpoint /messages/ que anuncia 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 el conjunto de pruebas con:

uv sync --all-extras
pytest -v tests

Ejecutar el servidor localmente

Para iniciar el servidor automáticamente (útil cuando desarrollas o pruebas), ejecuta:

mcp run src/intervals_mcp_server/server.py

Habilitar el registro de depuración

Para capturar los registros del servidor para depurar, rodea el comando con un shell y redirige el error estándar a un archivo.

macOS/Linux — modifica tu claude_desktop_config.json de esta forma:

{
  "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"
      }
    }
  }
}

Después, monitoriza 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 de esta forma:

{
  "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"
      }
    }
  }
}

Después, visualiza 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

Destacado

Glama.ai