Intervals.icu MCP Server

Сервер Model Context Protocol (MCP) для подключения Claude и ChatGPT к API Intervals.icu. Он предоставляет инструменты для аутентификации и получения данных по активностям, событиям, данным о самочувствии, кривым мощности и настраиваемым элементам.

Если вы считаете сервер Model Context Protocol (MCP) полезным, пожалуйста, поддержите его дальнейшее развитие пожертвованием.

Requirements

• Python 3.12 или выше

• Model Context Protocol (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

Настройка

1. Установка uv (рекомендуется)

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"

После установки найдите полный путь к uv — он понадобится позже при настройке Claude Desktop:

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

2. Клонируйте этот репозиторий

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

3. Создайте и активируйте виртуальное окружение

# 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. Синхронизируйте зависимости проекта

uv sync

5. Настройте переменные окружения

Скопируйте .env.example и назовите его .env, выполнив следующую команду:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Затем отредактируйте файл .env и укажите свой ID спортсмена Intervals.icu и API-ключ:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Получение API-ключа Intervals.icu

1. Войдите в свой аккаунт Intervals.icu

2. Перейдите в раздел Settings > API

3. Создайте новый API-ключ

Поиск вашего ID спортсмена

Ваш ID спортсмена обычно виден в URL-адресе, когда вы вошли в Intervals.icu. Выглядит это так:

• https://intervals.icu/athlete/i12345/..., где i12345 — это ваш ID спортсмена

Обновление

Этот проект активно развивается, новые функции и исправления добавляются регулярно. Чтобы оставаться в актуальном состоянии, выполните следующие шаги:

1. Получите последние изменения из ветки main

⚠️ Убедитесь, что у вас нет незакоммиченных изменений, перед выполнением этой команды.

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Обновите зависимости Python

Активируйте виртуальное окружение и синхронизируйте зависимости:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

Устранение неполадок

Если Claude Desktop не работает из-за изменений в конфигурации, выполните следующие шаги:

1. Удалите существующую запись Intervals.icu из claude_desktop_config.json.

2. Заново настройте Claude Desktop из каталога intervals-mcp-server.

macOS/Linux:

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

Windows: добавьте запись вручную, как описано в разделе настройки Windows.

Частые ошибки

spawn uv ENOENT — Claude Desktop не может найти исполняемый файл uv. Используйте полный путь к uv в поле command. Чтобы узнать его, выполните which uv (macOS/Linux) или where.exe uv (Windows).

spawn /Users/... ENOENT в Windows — В конфигурационном файле указан путь в стиле macOS/Linux. Замените его правильным путём Windows с обратными слэшами, как описано в разделе настройки Windows ниже.

Установка из Microsoft Store: изменения конфигурации не действуют — Возможно, вы редактируете не тот файл конфигурации. Claude Desktop, установленный из Microsoft Store, читает конфигурацию из AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, а не из AppData\Roaming\Claude\.

Использование с Claude

1. Настройка Claude Desktop

Чтобы использовать этот сервер с Claude Desktop, необходимо добавить его в конфигурацию Claude Desktop.

macOS/Linux

1. Выполните следующую команду из каталога intervals-mcp-server, чтобы настроить Claude Desktop:

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

2. Если вы откроете файл конфигурации приложения Claude Desktop claude_desktop_config.json, он должен выглядеть следующим образом:

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

Где /path/to/ — это путь к папке с кодом intervals-mcp-server в вашей системе.

Windows

Команда mcp install может завершиться ошибкой в Windows из-за проблем с окружением или правами доступа. Вместо этого настройте Claude Desktop вручную:

1. Найдите файл конфигурации Claude Desktop. Если Claude Desktop был установлен из Microsoft Store, конфигурация находится по адресу:

C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Если он был установлен через стандартный установщик, он может находиться по адресу:

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

Если файла или папки не существует, создайте их.

2. Добавьте следующую запись в claude_desktop_config.json, заменив заполнители своими фактическими значениями:

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

• Используйте двойные обратные слэши (\\) для всех путей Windows в JSON.

• Чтобы узнать полный путь к uv.exe, выполните where.exe uv в PowerShell.

• Чтобы узнать полный путь к клонированному репозиторию, выполните pwd из папки intervals-mcp-server.

Примечание для установок из Microsoft Store: Claude Desktop, установленный из Microsoft Store, хранит свою конфигурацию в изолированной папке AppData\Local\Packages\.... Редактирование AppData\Roaming\Claude\claude_desktop_config.json не даст эффекта — убедитесь, что вы редактируете правильный файл.

3. Перезапустите Claude Desktop.

2. Использование MCP-сервера с Claude

Когда сервер работает и Claude Desktop настроен, вы можете использовать следующие инструменты, чтобы задавать вопросы о прошлых и предстоящих активностях, событиях и данных о самочувствии.

• get_activities: получение списка активностей

• get_activity_details: получение подробной информации о конкретной активности

• get_activity_intervals: получение подробных данных по интервалам для конкретной активности

• get_activity_streams: получение потоков необработанных данных (мощность, сердечный ритм и т. д.) для конкретной активности

• get_athlete_power_curves: получение кривых лучшей мощности за выбранные длительности и периоды времени

• get_wellness_data: получение данных о самочувствии

• get_events: получение предстоящих событий (тренировок, гонок и т. д.)

• get_event_by_id: получение подробной информации о конкретном событии

• add_or_update_event: создание или обновление события (тренировки, гонки, заметки и т. д.)

• delete_event: удаление конкретного события

• delete_events_by_date_range: удаление событий в указанном диапазоне дат

• get_custom_items: получение настраиваемых элементов (графиков, настраиваемых полей, зон и т. д.) для спортсмена

• get_custom_item_by_id: получение подробной информации о конкретном настраиваемом элементе

• create_custom_item: создание нового настраиваемого элемента для спортсмена

• update_custom_item: обновление существующего настраиваемого элемента

• delete_custom_item: удаление настраиваемого элемента

Использование с ChatGPT

Бета-версия MCP-коннекторов ChatGPT также умеет работать с этим сервером через SSE-транспорт.

1. Запустите сервер в режиме SSE, чтобы он предоставлял конечные точки /sse и /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

В логе запуска выводятся полные URL (например, http://127.0.0.1:8765/sse). ChatGPT нужен публичный URL, поэтому, если вы не публикуете сервер напрямую, перенаправьте порт с помощью такого инструмента, как ngrok http 8765.

2. В ChatGPT откройте Settings → Features → Custom MCP Connectors и нажмите Add. Заполните поля:

   • Name: Intervals.icu

   • MCP Server URL: https://<ваш-публичный-хост>/sse

   • Authentication: оставьте значение No authentication, если вы не защитили свой туннель.

   Здесь можно повторно использовать тот же URL туннеля ngrok http 8765; главное, чтобы он перенаправлял на тот же хост/порт, который вы настроили выше.

3. Сохраните коннектор и откройте новый чат. ChatGPT будет держать SSE-соединение открытым и отправлять последующие POST-запросы на endpoint /messages/, объявленный сервером. Если вы перезапускаете MCP-сервер или туннель, снова выполните SSE-команду и обновите URL коннектора, если он изменился.

Разработка и тестирование

Установите зависимости для разработки и выполните тесты командой:

uv sync --all-extras
pytest -v tests

Локальный запуск сервера

Чтобы запустить сервер вручную (например, при разработке и тестировании), выполните:

mcp run src/intervals_mcp_server/server.py

Включение отладочного логирования

Чтобы сохранять журналы сервера для отладки, оберните команду в оболочку и перенаправьте stderr в файл.

macOS/Linux — измените файл claude_desktop_config.json следующим образом:

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

Затем просматривайте журнал в реальном времени с помощью команды tail:

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

Windows — измените файл claude_desktop_config.json следующим образом:

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

Затем следите за журналом в реальном времени с помощью PowerShell:

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

Лицензия

GNU General Public License v3.0

Избранное

Glama.ai