Intervals.icu

Conecta-se à API do Intervals.icu para recuperar atividades, eventos e dados de bem-estar.

Documentação

Servidor MCP Intervals.icu

Servidor Model Context Protocol (MCP) para conectar Claude e ChatGPT à API do Intervals.icu. Ele fornece ferramentas para autenticação e recuperação de dados de atividades, eventos, dados de bem-estar, curvas de potência e itens personalizados.

Se você achar o servidor Model Context Protocol (MCP) útil, considere apoiar seu desenvolvimento contínuo com uma doação.

Requisitos

Python 3.12 ou superior
Model Context Protocol (MCP) Python SDK
httpx
python-dotenv

Configuração

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"

Após a instalação, encontre o caminho completo para uv — você precisará dele mais tarde ao configurar o Claude Desktop:

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

2. Clonar este repositório

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

3. Criar e ativar um ambiente 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 dependências do projeto

uv sync

5. Configurar variáveis de ambiente

Faça uma cópia de .env.example e nomeie-a como .env executando o seguinte comando:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Em seguida, edite o arquivo .env e defina seu ID de atleta e chave de API do Intervals.icu:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Obtendo sua chave de API do Intervals.icu

Faça login na sua conta do Intervals.icu
Vá para Configurações > API
Gere uma nova chave de API

Encontrando seu ID de atleta

Seu ID de atleta geralmente fica visível na URL quando você está logado no Intervals.icu. Ele se parece com:

https://intervals.icu/athlete/i12345/... onde i12345 é seu ID de atleta

Atualização

Este projeto é desenvolvido ativamente, com novos recursos e correções adicionados regularmente. Para se manter atualizado, siga estes passos:

1. Puxe as alterações mais recentes de `main`

⚠️ Certifique-se de não ter alterações não commitadas antes de executar este comando.

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Atualizar dependências do Python

Ative seu ambiente virtual e sincronize as dependências:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

Solução de problemas

Se o Claude Desktop falhar devido a alterações de configuração, siga estes passos:

Exclua a entrada existente de Intervals.icu em claude_desktop_config.json.
Reconfigure o Claude Desktop a partir do diretório intervals-mcp-server.

macOS/Linux:

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

Windows: Re-adicione a entrada manualmente conforme descrito na seção de configuração do Windows.

Erros comuns

spawn uv ENOENT — O Claude Desktop não consegue encontrar o executável uv. Use o caminho completo para uv no campo command. Execute which uv (macOS/Linux) ou where.exe uv (Windows) para obtê-lo.

spawn /Users/... ENOENT no Windows — O arquivo de configuração contém um caminho no estilo macOS/Linux. Substitua-o pelo caminho correto do Windows usando barras invertidas, conforme descrito na seção de configuração do Windows abaixo.

Instalação da Microsoft Store: alterações de configuração não têm efeito — Você pode estar editando o arquivo de configuração errado. O Claude Desktop instalado pela Microsoft Store lê de AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, não de AppData\Roaming\Claude\.

Uso com Claude

1. Configurar o Claude Desktop

Para usar este servidor com o Claude Desktop, você precisa adicioná-lo à configuração do Claude Desktop.

macOS/Linux

Execute o seguinte a partir do diretório intervals-mcp-server para configurar o Claude Desktop:

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

Se você abrir o arquivo de configuração do Claude Desktop App claude_desktop_config.json, ele deve ficar assim:

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

Onde /path/to/ é o caminho para a pasta de código intervals-mcp-server no seu sistema.

Windows

O comando mcp install pode falhar no Windows devido a problemas de ambiente ou permissão. Em vez disso, configure o Claude Desktop manualmente:

Encontre o arquivo de configuração do Claude Desktop. Se o Claude Desktop foi instalado pela Microsoft Store, a configuração está localizada em:
```
C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
```
Se instalado via instalador padrão, pode estar em:
```
C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json
```
Se o arquivo ou pasta não existir, crie-o.
Adicione a seguinte entrada a claude_desktop_config.json, substituindo os espaços reservados pelos seus valores reais:

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

Use barras invertidas duplas (\\) para todos os caminhos do Windows em JSON.
Para encontrar o caminho completo para uv.exe, execute where.exe uv no PowerShell.
Para encontrar o caminho completo do repositório clonado, execute pwd de dentro da pasta intervals-mcp-server.

Nota para instalações da Microsoft Store: O Claude Desktop instalado pela Microsoft Store isola sua configuração em AppData\Local\Packages\.... Editar AppData\Roaming\Claude\claude_desktop_config.json não terá efeito — certifique-se de editar o arquivo correto.

Reinicie o Claude Desktop.

2. Usar o servidor MCP com Claude

Uma vez que o servidor esteja em execução e o Claude Desktop esteja configurado, você pode usar as seguintes ferramentas para fazer perguntas sobre suas atividades passadas e futuras, eventos e dados de bem-estar.

get_activities: Recuperar uma lista de atividades
get_activity_details: Obter informações detalhadas para uma atividade específica
get_activity_intervals: Obter dados detalhados de intervalos para uma atividade específica
get_activity_streams: Obter fluxos de dados brutos (potência, frequência cardíaca, etc.) para uma atividade específica
get_athlete_power_curves: Obter melhores curvas de potência para durações e períodos selecionados
get_wellness_data: Buscar dados de bem-estar
get_events: Recuperar eventos futuros (treinos, corridas, etc.)
get_event_by_id: Obter informações detalhadas para um evento específico
add_or_update_event: Criar ou atualizar um evento (treino, corrida, nota, etc.)
delete_event: Excluir um evento específico
delete_events_by_date_range: Excluir eventos dentro de um intervalo de datas
get_custom_items: Obter itens personalizados (gráficos, campos personalizados, zonas, etc.) para um atleta
get_custom_item_by_id: Obter informações detalhadas para um item personalizado específico
create_custom_item: Criar um novo item personalizado para um atleta
update_custom_item: Atualizar um item personalizado existente
delete_custom_item: Excluir um item personalizado

Uso com ChatGPT

Os conectores MCP beta do ChatGPT também podem conversar com este servidor através do transporte SSE.

Inicie o servidor no modo SSE para que ele exponha os endpoints /sse e /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
```
O log de inicialização imprime as URLs completas (por exemplo, http://127.0.0.1:8765/sse). O ChatGPT precisa dessa URL pública, então encaminhe a porta com uma ferramenta como ngrok http 8765 se você não estiver expondo o servidor diretamente.
No ChatGPT, abra Configurações → Recursos → Conectores MCP Personalizados e clique em Adicionar. Preencha:
- Nome: Intervals.icu
- URL do Servidor MCP: https://<your-public-host>/sse
- Autenticação: deixe como Sem autenticação a menos que você tenha protegido seu túnel.
Você pode reutilizar a mesma URL de túnel ngrok http 8765 aqui; apenas certifique-se de que ela encaminhe para o host/porta que você exportou acima.
Salve o conector e abra um novo chat. O ChatGPT manterá a conexão SSE aberta e enviará solicitações de acompanhamento para o endpoint /messages/ anunciado pelo servidor. Se você reiniciar o servidor MCP ou o túnel, execute novamente o comando SSE e atualize a URL do conector se ela mudar.

Desenvolvimento e testes

Instale as dependências de desenvolvimento e execute a suíte de testes com:

uv sync --all-extras
pytest -v tests

Executando o servidor localmente

Para iniciar o servidor manualmente (útil ao desenvolver ou testar), execute:

mcp run src/intervals_mcp_server/server.py

Habilitando log de depuração

Para capturar logs do servidor para depuração, envolva o comando em um shell e redirecione o stderr para um arquivo.

macOS/Linux — modifique seu claude_desktop_config.json assim:

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

Em seguida, monitore o arquivo de log para ver a saída em tempo real:

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

Windows — modifique seu claude_desktop_config.json assim:

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

Em seguida, monitore o arquivo de log em tempo real usando o PowerShell:

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

Licença

GNU General Public License v3.0

Intervals.icu

Documentação

Servidor MCP Intervals.icu

Requisitos

Configuração

1. Instalar uv (recomendado)

2. Clonar este repositório

3. Criar e ativar um ambiente virtual

4. Sincronizar dependências do projeto

5. Configurar variáveis de ambiente

Obtendo sua chave de API do Intervals.icu

Encontrando seu ID de atleta

Atualização

1. Puxe as alterações mais recentes de `main`

2. Atualizar dependências do Python

Solução de problemas

Erros comuns

Uso com Claude

1. Configurar o Claude Desktop

macOS/Linux

Windows

2. Usar o servidor MCP com Claude

Uso com ChatGPT

Desenvolvimento e testes

Executando o servidor localmente

Habilitando log de depuração

Licença

Destaques

Glama.ai

Intervals.icu

Documentação

Servidor MCP Intervals.icu

Requisitos

Configuração

1. Instalar uv (recomendado)

2. Clonar este repositório

3. Criar e ativar um ambiente virtual

4. Sincronizar dependências do projeto

5. Configurar variáveis de ambiente

Obtendo sua chave de API do Intervals.icu

Encontrando seu ID de atleta

Atualização

1. Puxe as alterações mais recentes de main

2. Atualizar dependências do Python

Solução de problemas

Erros comuns

Uso com Claude

1. Configurar o Claude Desktop

macOS/Linux

Windows

2. Usar o servidor MCP com Claude

Uso com ChatGPT

Desenvolvimento e testes

Executando o servidor localmente

Habilitando log de depuração

Licença

Destaques

Glama.ai

1. Puxe as alterações mais recentes de `main`