Intervals.icu MCP Server & AI Running Coach

An official-grade Model Context Protocol (MCP) Server and AI Running Coach Intelligence System for Intervals.icu.

Empower your AI assistants (Claude Desktop, Antigravity, Cursor, VS Code Cline / Roo-Code) to read real-time telemetry, evaluate acute & chronic training load (CTL/ATL/TSB/ACWR), compute Jack Daniels VDOT & pace zones, calculate cardiac drift & aerobic decoupling, predict race times, schedule tapering, and publish structured workouts directly to your Intervals.icu calendar.

📑 Table of Contents

• ✨ Key Capabilities

• 🚀 3-Minute Quickstart

• ⚙️ Configuration (API Key & Athlete ID)

• 🔌 MCP Client Setup Guides

  • Claude Desktop

  • Antigravity

  • Cursor

  • VS Code (Cline / Roo-Code)

• 🤖 AI Workflows & Slash Commands Directory

• 👤 Customizing Your Athlete Profile

• 💬 Example Chat Prompts

• 🛠️ Full MCP Tools Reference

• 🧪 Development & Testing

• 📄 License

✨ Key Capabilities

• 🏃 Real-time Telemetry & Stream Ingestion: Extract watts, heart rate, cadence, velocity, and interval splits from completed sessions.

• ⚡ Aerobic Decoupling & Cardiac Drift Engine: Compute Efficiency Factor (EF) $H_1$ vs $H_2$ to detect cardiovascular drift (>5%) or dehydration.

• 🩹 Unified Recovery & Readiness Scoring: 0–100% composite score combining TSB, ACWR, Sleep Score, HRV, and RHR Spike into Green/Yellow/Red action signals.

• 🏆 Race Time Predictor & Tapering Planner: Jack Daniels VDOT formula + CTL fitness and TSB freshness adjustments + 2–3 week volume reduction generator.

• ⚖️ ACWR & Weekly Load Budgeting: Safe volume progression caps (Long Run 30–35%, Quality 15–20%, Easy 45–55%) based on 42-day rolling baseline.

• 📅 Structured Workout Builder: Publish workouts to the Intervals.icu calendar using native Intervals Text DSL (Warmup, Main Set Nx, Cooldown).

🚀 3-Minute Quickstart

1. Prerequisites

• Node.js: >= 18.0.0

• Package Manager: pnpm (recommended), npm, or yarn

• Intervals.icu Account & API Key

2. Clone & Build

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

⚙️ Configuration

Retrieve your credentials from Intervals.icu Settings:

1. Scroll down to the Developer section.

2. Copy your API Key (e.g. your_api_key_here).

3. Note your Athlete ID (found in settings or profile URL, e.g. i12345 or use self).

Environment Variables

🔌 MCP Client Setup Guides

1. Claude Desktop

Add the following to your 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

In your Antigravity MCP settings or .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

In Cursor Settings > Features > MCP Servers or .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)

In 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 Skills & Slash Commands Directory

This repository comes pre-loaded with 11 Production-Ready Modern Skills in .agents/skills/ that you can trigger using slash commands (with first-class support for autonomous agent discovery):

📖 Comprehensive Usage Guide: For an in-depth operational timeline of when and how to run each command across macrocycles, mesocycles, and daily routines, see docs/WORKFLOWS-GUIDE.md.

👤 Customizing Your Athlete Profile

To give your AI Assistant accurate coaching context, configure your profile in .agents/skills/running-coach-analysis/SKILL.md:

1. Section 2 (Athlete Profile): Fill in your name, age, fallback weight, and target race goals.

2. Section 3 (Physiological Baseline): Provide fallback CP/FTP, LTHR, Max HR, and Resting HR (note: active values are automatically synced dynamically via MCP).

3. Section 4 (Weekly Structure & Blueprints): Define your weekly training frequency, preferred workout sessions (e.g. Subthreshold, VO2Max, Long Run), and specific power/pace targets.

💬 Example Chat Prompts

Here are examples of how you can chat with your AI Running Coach:

1. Daily Post-Run Evaluation

"Here is my workout from this morning. Please run /run-report on my latest activity. RPE was 6/10, legs felt springy during the 3rd interval."

2. Pre-Workout Readiness Check

"/readiness-check — Am I well-recovered for today's Subthreshold interval session, or should I cap intensity to Zone 2?"

3. Weekly Volume Allocation

"/weekly-budget distance — What is my recommended total mileage and Long Run ceiling for this week?"

4. Race Day Prediction & Tapering

"/predict-race — My active VDOT is 50 and my target Half Marathon race is on 2026-10-15. Give me finish time prediction and 2-week tapering schedule."

5. Schedule a Workout to Calendar

"/create-workout — Schedule a 50-minute Subthreshold session (Warmup 12m, 6x3m @ 95-98% CP with 1m rest, Cooldown 6m) for tomorrow."

🛠️ Full MCP Tools Reference

The server exposes 20+ tools grouped by category:

🏃 1. Activities & Streams

• get_activities: Fetch activities within a date range (oldest, newest, type).

• get_activity_details: Retrieve full telemetry, metrics, and athlete physiological values for an activity ID.

• get_activity_intervals: Extract lap and work/rest interval breakdowns.

• get_activity_streams: Access raw time-series stream data (watts, heartrate, cadence, velocity_smooth, altitude).

• get_activity_messages: Read activity comments and notes.

• add_activity_message: Post coaching feedback to an activity.

👤 2. Athlete Biometrics & Zones

• get_athlete_profile: Retrieve athlete profile (FTP, LTHR, Max HR, weight, resting HR).

• get_training_zones: Access power, heart rate, and pace training zone boundaries.

🧮 3. Physiology & Endurance Intelligence (Offline)

• calculate_vdot: Compute Jack Daniels VDOT & VO₂max from race/tempo time trial.

• calculate_pace_zones: Compute 5 pace training zones (Easy, Marathon, Threshold, Interval, Repetition) in MM:SS/km.

• predict_race_time: Predict race finish time and pace (5K, 10K, HM, FM, or custom km) from VDOT with CTL fitness and TSB freshness adjustments.

• calculate_taper_plan: Generate weekly volume reduction schedule (75% → 50% → 30%) for peak TSB freshness on race day.

• analyze_cardiac_drift: Compute Efficiency Factor (EF) and Aerobic Decoupling % from raw telemetry streams (heartrateStream, powerOrSpeedStream).

• calculate_readiness_score: Compute unified recovery score (0–100%, Green/Yellow/Red) combining TSB, ACWR, Sleep, HRV, and RHR.

⚖️ 4. Training Load & Periodization (Offline)

• analyze_training_load: Compute ACWR (ATL/CTL), classify TSB readiness zones, and evaluate ramp rate injury risk.

• calculate_weekly_budget: Calculate safe weekly training budget (Total Volume, Long Run 30–35%, Quality 15–20%, Easy 45–55%) based on 42d rolling average.

📅 5. Calendar & Workout Builder

• get_events: Retrieve calendar items (planned workouts, notes, races) in date range.

• get_event_by_id: Get detailed event data by ID.

• create_running_workout: Structured Workout Builder — Validate and publish structured workouts to Intervals.icu calendar using Text DSL.

• add_or_update_planned_workout: Create or update planned workout events.

• add_or_update_note: Add text notes to calendar dates.

• delete_event: Remove calendar events by ID.

• get_workout_library: Search workout template library.

• get_workout_by_id: Get workout template details.

🚴 6. Gear & Power Curves

• get_gear_list: List registered bikes, shoes, and equipment with mileage (cached 30m).

• get_athlete_power_curves: Fetch power duration curves (cached 60m).

💚 7. Wellness & Fitness Time-Series

• get_wellness_data: Retrieve daily wellness entries (sleep score, HRV, resting HR, fatigue, soreness, weight).

• get_fitness_chart: Retrieve time-series fitness data (ctl, atl, tsb, rampRate, eftp).

🧪 Development & Testing

Run the full unit test suite:

# Run Vitest unit tests
pnpm test

# Build TypeScript
pnpm run build

# Watch mode during development
pnpm exec vitest

Includes 59+ unit tests covering API client auto-retry on HTTP 429, LRU TTL caching, Jack Daniels VDOT math, race prediction, cardiac drift analysis, recovery scoring, ACWR analytics, and workout DSL validation.

📄 License

This project is licensed under the MIT License © Muhammad Hadid Wiransetyo.