intervals-icu-mcp

Servidor MCP Intervals.icu

Um servidor Model Context Protocol (MCP) para integração com Intervals.icu. Acesse seus dados de treino, métricas de bem-estar e análises de desempenho através do Claude, ChatGPT e outros LLMs.

Originalmente baseado em eddmann/intervals-icu-mcp (licenciado sob MIT). Este projeto é uma continuação independente com correções significativas de bugs e novos recursos — consulte CHANGELOG.md para detalhes.

Visão Geral

62 ferramentas abrangendo atividades, análise de atividades, mensagens de atividades, perfil do atleta, bem-estar, eventos/calendário, curvas de desempenho, biblioteca de treinos, equipamentos, configurações de esporte e itens personalizados — além de 4 Recursos MCP (perfil do atleta, sintaxe de treinos, categorias de eventos, esquemas de itens personalizados) e 7 Prompts MCP (análise de treino, verificação de recuperação, planejamento semanal e mais). Consulte Ferramentas Disponíveis para o detalhamento por categoria.

Início Rápido

Ou para o Claude Desktop, em 30 segundos:

1. Obtenha sua chave de API e ID do atleta
2. Adicione isto à configuração do seu 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. Reinicie o Claude e pergunte "Mostre-me minhas atividades dos últimos 7 dias."

Prefere Claude Code, Cursor ou ChatGPT? Consulte Configuração do Cliente. Quer executar a partir do código-fonte ou com Docker? Consulte Instalação e Configuração.

Pré-requisitos

Instale o uv — ele gerencia Python, dependências e execução em uma única ferramenta. brew install uv no macOS/Linux, ou powershell -c "irm https://astral.sh/uv/install.ps1 | iex" no Windows. A partir daí, uvx baixa Python e o pacote automaticamente. Docker também é suportado como alternativa.

Configuração da Chave de API do Intervals.icu

Antes da instalação, obtenha sua chave de API do Intervals.icu:

1. Vá para https://intervals.icu/settings → Desenvolvedor → Criar Chave de API.
2. Copie a chave e anote seu ID do Atleta na URL do seu perfil (formato: i123456).

Instalação e Configuração

Nada para instalar separadamente se você usar a configuração recomendada. uvx (que acompanha o uv) baixa e armazena em cache automaticamente o pacote intervals-icu-mcp na primeira vez que seu cliente MCP o inicia — basta colar o trecho de configuração de Configuração do Cliente no seu cliente e pronto.

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

Configuração do Cliente

O servidor fala MCP via stdio e funciona com qualquer cliente compatível. Clique em um cliente para expandir. Se você seguiu o Início Rápido (uvx), use o primeiro bloco de configuração; se usou a alternativa de código-fonte ou Docker acima, use a variante correspondente dentro do mesmo bloco recolhível.

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

Peça ao Claude para interagir com seus dados do Intervals.icu em linguagem natural. Alguns prompts iniciais:

"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 o catálogo completo de exemplos de prompts por categoria, consulte docs/examples.md.

Ferramentas Disponíveis

62 ferramentas, 4 recursos e 7 modelos de prompt. Resumo em uma linha abaixo — referência completa em docs/tools.md.

Modo de Segurança de Exclusão

Ferramentas destrutivas são controladas pela variável de ambiente opcional INTERVALS_ICU_DELETE_MODE (safe / full / none, padrão safe) — uma proteção no lado do servidor fora do alcance do modelo, para que ferramentas não registradas não possam ser invocadas. Consulte docs/tools.md para a tabela completa de modos, envelope de resposta e justificativa do buffer de TZ.

Implantação Remota (HTTP / SSE)

O servidor executa via stdio por padrão — o transporte correto para clientes locais como Claude Desktop, Claude Code e Cursor. Transportes HTTP e SSE estão disponíveis para uso remoto ou hospedado.

⚠️ O MCP não possui autenticação integrada — nunca exponha um servidor em modo HTTP a uma rede não confiável sem um túnel (Tailscale, Cloudflare Tunnel) ou um proxy reverso com autenticação.

Consulte docs/remote-deployment.md para flags de transporte e o modelo de segurança completo.

Documentação

• Exemplos de prompts — catálogo completo de prompts em linguagem natural por categoria
• Referência de ferramentas — inventário completo de ferramentas, recursos e prompts
• Visão geral da arquitetura — como servidor, middleware, cliente e ferramentas se encaixam
• Implantação remota (HTTP/SSE) — transportes, flags e o modelo de segurança para configurações hospedadas/remotas
• Guia de testes — convenções para pytest + respx, fixtures e execução da suíte
• Changelog — histórico de versões
• Adicionando uma nova ferramenta — fluxo de trabalho passo a passo para contribuidores

Contribuindo

Issues e pull requests são bem-vindos. Antes de abrir um PR, execute make can-release localmente para corresponder ao que o CI aplica (ruff, pyright, pytest). Para novas ferramentas, siga o padrão em .claude/skills/add-tool/SKILL.md e adicione um arquivo de teste com mock respx junto à implementação.

Licença

Licença MIT — consulte o arquivo LICENSE para detalhes.

Aviso Legal

Este projeto não é afiliado, endossado ou patrocinado pela Intervals.icu. Todos os nomes de produtos, logotipos e marcas são propriedade de seus respectivos proprietários.