Intervals.icu MCP 서버 및 AI 러닝 코치

Intervals.icu를 위한 공식급 Model Context Protocol (MCP) 서버 및 AI 러닝 코치 인텔리전스 시스템입니다.

AI 어시스턴트(Claude Desktop, Antigravity, Cursor, VS Code Cline / Roo-Code)에 실시간 원격 측정 데이터 읽기, 급성 및 만성 훈련 부하(CTL/ATL/TSB/ACWR) 평가, Jack Daniels VDOT 및 페이스 존 계산, 심박수 드리프트 및 유산소 디커플링 계산, 레이스 시간 예측, 테이퍼링 일정 수립, Intervals.icu 캘린더에 구조화된 워크아웃 게시 기능을 제공합니다.

📑 목차

• ✨ 주요 기능

• 🚀 3분 퀵스타트

• ⚙️ 설정 (API 키 및 운동선수 ID)

• 🔌 MCP 클라이언트 설정 가이드

  • Claude Desktop

  • Antigravity

  • Cursor

  • VS Code (Cline / Roo-Code)

• 🤖 AI 워크플로우 및 슬래시 커맨드 디렉토리

• 👤 운동선수 프로필 사용자 지정

• 💬 예시 채팅 프롬프트

• 🛠️ 전체 MCP 도구 참조

• 🧪 개발 및 테스트

• 📄 라이선스

Related MCP server: Intervals.icu MCP Server

✨ 주요 기능

• 🏃 실시간 원격 측정 및 스트림 수집: 완료된 세션에서 와트, 심박수, 케이던스, 속도, 인터벌 스플릿 추출.

• ⚡ 유산소 디커플링 및 심장 드리프트 엔진: 효율 계수(EF) $H_1$ vs $H_2$를 계산하여 심혈관 드리프트(>5%) 또는 탈수 감지.

• 🩹 통합 회복 및 준비 상태 점수: TSB, ACWR, 수면 점수, HRV, RHR 스파이크를 결합한 0–100% 복합 점수로 Green/Yellow/Red 실행 신호 제공.

• 🏆 레이스 시간 예측 및 테이퍼링 플래너: Jack Daniels VDOT 공식 + CTL 피트니스 및 TSB 컨디션 조정 + 2–3주 볼륨 감소 생성기.

• ⚖️ ACWR 및 주간 부하 예산 관리: 42일 롤링 기준선 기반 안전한 볼륨 증가 상한(롱런 30–35%, 퀄리티 15–20%, 이지 45–55%).

• 📅 구조화된 워크아웃 빌더: 네이티브 Intervals Text DSL(Warmup, Main Set Nx, Cooldown)을 사용하여 Intervals.icu 캘린더에 워크아웃 게시.

🚀 3분 퀵스타트

1. 사전 요구 사항

• Node.js: >= 18.0.0

• 패키지 매니저: pnpm (권장), npm 또는 yarn

• Intervals.icu 계정 및 API 키

2. 클론 및 빌드

git clone https://github.com/hadidwirsty/intervals-icu-mcp.git
cd intervals-icu-mcp
pnpm install
pnpm run build

⚙️ 설정

Intervals.icu 설정에서 자격 증명을 확인하세요:

1. 개발자(Developer) 섹션으로 스크롤합니다.

2. API 키를 복사합니다 (예: your_api_key_here).

3. **운동선수 ID(Athlete ID)**를 확인합니다 (설정 또는 프로필 URL에서 확인 가능, 예: i12345 또는 self 사용).

환경 변수

🔌 MCP 클라이언트 설정 가이드

1. Claude Desktop

claude_desktop_config.json에 다음을 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

2. Antigravity

Antigravity MCP 설정 또는 .gemini/config/mcp.json에서:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

3. Cursor

Cursor 설정 > 기능 > MCP 서버 또는 .cursor/mcp.json에서:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

4. VS Code (Cline / Roo-Code)

cline_mcp_settings.json에서:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🤖 AI 워크플로우 및 슬래시 커맨드 디렉토리

이 저장소에는 .agents/workflows/에 11개의 프로덕션 준비 완료 AI 워크플로우가 사전 탑재되어 있으며, 슬래시 커맨드로 실행할 수 있습니다:

👤 운동선수 프로필 사용자 지정

AI 어시스턴트에게 정확한 코칭 컨텍스트를 제공하려면 .agents/skills/running-coach-analysis/SKILL.md에서 프로필을 구성하세요:

1. 섹션 2 (운동선수 프로필): 이름, 나이, 기본 체중, 목표 레이스 목표를 입력합니다.

2. 섹션 3 (생리학적 기준치): 기본 CP/FTP, LTHR, 최대 심박수, 안정 시 심박수를 제공합니다 (참고: 활성 값은 MCP를 통해 동적으로 자동 동기화됨).

3. 섹션 4 (주간 구조 및 블루프린트): 주간 훈련 빈도, 선호 워크아웃 세션(예: 역치 이하, VO2Max, 롱런), 특정 파워/페이스 목표를 정의합니다.

💬 예시 채팅 프롬프트

AI 러닝 코치와 대화할 수 있는 예시입니다:

1. 일일 러닝 후 평가

"오늘 아침 운동 기록입니다. 최신 활동에 대해 /run-report를 실행해 주세요. RPE는 6/10이었고, 3번째 인터벌에서 다리가 탄력 있었습니다."

2. 운동 전 준비 상태 확인

"/readiness-check — 오늘 역치 이하 인터벌 세션을 하기에 회복이 충분한가요, 아니면 강도를 존 2로 제한해야 하나요?"

3. 주간 볼륨 배분

"/weekly-budget distance — 이번 주 권장 총 주행 거리와 롱런 상한선은 얼마인가요?"

4. 레이스 데이 예측 및 테이퍼링

"/predict-race — 현재 VDOT은 50이고 목표 하프마라톤 레이스는 2026-10-15입니다. 완주 시간 예측과 2주 테이퍼링 일정을 알려주세요."

5. 캘린더에 워크아웃 일정 등록

"/create-workout — 내일 50분 역치 이하 세션(워밍업 12분, 6x3분 @ CP의 95-98% + 1분 휴식, 쿨다운 6분)을 일정에 등록해 주세요."

🛠️ 전체 MCP 도구 참조

서버는 카테고리별로 20개 이상의 도구를 제공합니다:

🏃 1. 활동 및 스트림

• get_activities: 날짜 범위 내 활동 조회 (oldest, newest, type).

• get_activity_details: 활동 ID에 대한 전체 원격 측정, 지표, 운동선수 생리학적 값 조회.

• get_activity_intervals: 랩 및 작업/휴식 인터벌 분석 추출.

• get_activity_streams: 원시 시계열 스트림 데이터 접근 (watts, heartrate, cadence, velocity_smooth, altitude).

• get_activity_messages: 활동 댓글 및 메모 읽기.

• add_activity_message: 활동에 코칭 피드백 게시.

👤 2. 운동선수 생체 데이터 및 존

• get_athlete_profile: 운동선수 프로필 조회 (FTP, LTHR, 최대 심박수, 체중, 안정 시 심박수).

• get_training_zones: 파워, 심박수, 페이스 훈련 존 경계값 접근.

🧮 3. 생리학 및 지구력 인텔리전스 (오프라인)

• calculate_vdot: 레이스/템포 타임 트라이얼에서 Jack Daniels VDOT 및 VO₂max 계산.

• calculate_pace_zones: MM:SS/km 단위의 5개 페이스 훈련 존 계산 (이지, 마라톤, 역치, 인터벌, 레페티션).

• predict_race_time: VDOT 기반 레이스 완주 시간 및 페이스 예측 (5K, 10K, HM, FM 또는 사용자 지정 km) + CTL 피트니스 및 TSB 컨디션 조정.

• calculate_taper_plan: 레이스 데이 최고 TSB 컨디션을 위한 주간 볼륨 감소 일정 생성 (75% → 50% → 30%).

• analyze_cardiac_drift: 원시 원격 측정 스트림(heartrateStream, powerOrSpeedStream)에서 효율 계수(EF) 및 유산소 디커플링 % 계산.

• calculate_readiness_score: TSB, ACWR, 수면, HRV, RHR을 결합한 통합 회복 점수 계산 (0–100%, Green/Yellow/Red).

⚖️ 4. 훈련 부하 및 주기화 (오프라인)

• analyze_training_load: ACWR(ATL/CTL) 계산, TSB 준비 상태 존 분류, 램프 레이트 부상 위험 평가.

• calculate_weekly_budget: 42일 롤링 평균 기반 주간 안전 훈련 예산 계산 (총 볼륨, 롱런 30–35%, 퀄리티 15–20%, 이지 45–55%).

📅 5. 캘린더 및 워크아웃 빌더

• get_events: 날짜 범위 내 캘린더 항목 조회 (계획된 워크아웃, 메모, 레이스).

• get_event_by_id: ID로 상세 이벤트 데이터 조회.

• create_running_workout: 구조화된 워크아웃 빌더 — Text DSL을 사용하여 구조화된 워크아웃을 검증하고 Intervals.icu 캘린더에 게시.

• add_or_update_planned_workout: 계획된 워크아웃 이벤트 생성 또는 업데이트.

• add_or_update_note: 캘린더 날짜에 텍스트 메모 추가.

• delete_event: ID로 캘린더 이벤트 삭제.

• get_workout_library: 워크아웃 템플릿 라이브러리 검색.

• get_workout_by_id: 워크아웃 템플릿 상세 정보 조회.

🚴 6. 장비 및 파워 커브

• get_gear_list: 등록된 자전거, 신발, 장비 및 주행 거리 목록 (30분 캐시).

• get_athlete_power_curves: 파워 지속 시간 커브 조회 (60분 캐시).

💚 7. 웰니스 및 피트니스 시계열

• get_wellness_data: 일일 웰니스 항목 조회(수면 점수, HRV, 안정 시 심박수, 피로, 근육통, 체중).

• get_fitness_chart: 시계열 피트니스 데이터 조회(ctl, atl, tsb, rampRate, eftp).

🧪 개발 및 테스트

전체 단위 테스트 스위트 실행:

# Run Vitest unit tests
pnpm test

# Build TypeScript
pnpm run build

# Watch mode during development
pnpm exec vitest

59개 이상의 단위 테스트 포함: HTTP 429 시 API 클라이언트 자동 재시도, LRU TTL 캐싱, Jack Daniels VDOT 수학, 레이스 예측, 심박수 드리프트 분석, 회복 점수, ACWR 분석, 운동 DSL 검증.

📄 라이선스

이 프로젝트는 MIT License © Muhammad Hadid Wiransetyo에 따라 라이선스가 부여됩니다.