Skip to main content
Glama
intervals-icu-mcp

intervals-icu-mcp

by hadidwirsty

Intervals.icu MCP Server & AI Running Coach

License: MIT Node.js Version TypeScript Model Context Protocol Tests

An official-grade Model Context Protocol (MCP) Server and AI Running Coach Intelligence System for Intervals.icu, built with dual-engine synergy for Garmin Connect.

Empower your AI assistants (Claude Desktop, Antigravity, Cursor, VS Code Cline / Roo-Code) to ingest real-time telemetry, evaluate acute & chronic training load (CTL/ATL/TSB/ACWR/Ramp Rate), compute Jack Daniels VDOT & Copeland Norwegian Singles interval matrices, diagnose Aerobic Deficiency Syndrome (ADS) via John Hadd & Uphill Athlete principles, analyze cardiovascular drift, predict race times, calculate carbohydrate fueling protocols, and publish structured workouts directly to your Intervals.icu calendar via Intervals Text DSL.


๐Ÿ“‘ Table of Contents


Related MCP server: intervals.icu-mcp

โœจ Key Capabilities

  • ๐Ÿƒ Activity Telemetry & Sensor 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.

  • ๐Ÿฉน Dual-Engine Recovery & Readiness Scoring: 0โ€“100% composite score combining TSB, ACWR, Sleep Score, HRV Status, and RHR Spike into Green/Yellow/Red action signals.

  • ๐Ÿ”ฌ John Hadd Physiology & ADS Diagnosis: 4-tier Aerobic Deficiency Syndrome (ADS) classifier using Uphill Athlete 10% Rule & Horwill's Rule, plus absolute HR training floors ($\le \text{HR}_{\max} - 50\text{ bpm}$).

  • ๐Ÿ‡ณ๐Ÿ‡ด Norwegian Singles Copeland Matrix: Deterministic sub-threshold repetition paces and power targets (Fast 3โ€“4m, Medium 4โ€“6m, Long 10โ€“12m) calibrated 5โ€“25 seconds slower than VDOT Threshold.

  • ๐Ÿ† Race Time Predictor & Tapering Planner: Jack Daniels VDOT formula + CTL fitness and TSB freshness adjustments + 10โ€“14 day volume reduction schedule.

  • ๐ŸŒ Race Fueling & Hydration Calculator: Precise carbohydrate hourly intake targets (dual-source Maltodextrin:Fructose), gel timing schedules, and tropical sweat-rate fluid balancing.

  • ๐Ÿ“… Structured Workout Builder & Publisher: Validate and publish workouts directly to your 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

Note on Submodules (Optional): The documentation submodule (docs/references/norwegian-singles) references upstream open-source literature. The server builds and runs completely independently without submodules. To clone literature references for offline reading, run git submodule update --init --recursive.


โš™๏ธ 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

Variable

Required

Description

INTERVALS_API_KEY

Yes

Your personal Intervals.icu API Key.

INTERVALS_ATHLETE_ID

Optional

Default Athlete ID (default: self). Can be overridden per call.

INTERVALS_API_BASE_URL

Optional

Base URL API Intervals.icu (default: https://intervals.icu/api/v1).


๐Ÿ”Œ 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": []
    }
  }
}

๐Ÿค– Unified AI Skills & Slash Commands Directory

This repository includes 6 Production-Grade Agent Skills in .agents/skills/ designed for autonomous agent execution:

๐Ÿ“– 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.

Slash Command

Skill File

Description & Methodology

/cek-kesiapan

SKILL.md

Dual-Engine physical readiness evaluation (0โ€“100% Green/Yellow/Red) combining Garmin Body Battery & HRV with Intervals.icu CTL/ATL/TSB and 5 fatigue Red Flags.

/lapor-lari

SKILL.md

Post-run comprehensive evaluation: power telemetry (% CP), Copeland Sub-T intensity compliance, cardiac drift / aerobic decoupling (< 5%), and automated calendar feedback.

/jadwal-minggu

SKILL.md

Weekly training scheduler based on 42-day rolling budget (Faris Salman / Steve Palladino), 3-1 block pattern, and one-click calendar publishing via Intervals Text DSL.

/kalibrasi-atlet

SKILL.md

Periodic fitness benchmark (every 4โ€“8 weeks): Jack Daniels VDOT, Copeland interval matrix, John Hadd absolute HR zones, ADS diagnosis, and Garmin Zone 2 audit.

/panduan-kekuatan

SKILL.md

Functional strength guide (22โ€“25 min) based on Stuart McGill Big 3 spinal protection and Running Anatomy kinetic chain strengthening (Soleus, Hamstrings, Hip Flexors).

/strategi-lomba

SKILL.md

Comprehensive race preparation: A/B/C Race priority hierarchy, A/B/C tapering schedules, Critical Power (% CP) split pacing, and carbohydrate/hydration protocols.


๐Ÿ’ฌ Example Chat Prompts

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

1. Daily Morning Readiness Check

"/cek-kesiapan โ€” Check my Garmin Body Battery, sleep data, and Intervals.icu fatigue load for today's session."

2. Post-Run Telemetry Evaluation

"/lapor-lari โ€” Analyze my latest morning interval session. Check my sub-threshold power compliance and aerobic decoupling."

3. Weekly Schedule Generation

"/jadwal-minggu โ€” Plan my training for next week using the 42-day rolling budget and publish the sessions to my Intervals.icu calendar."

4. Periodic Calibration

"/kalibrasi-atlet 5k 24:15 โ€” Recalibrate my VDOT, Copeland interval cards, and John Hadd heart rate zones based on my latest time-trial."


๐Ÿ› ๏ธ Full MCP Tools Reference (40 Tools)

The server exposes 40 specialized tools across 10 functional domains:

๐Ÿƒ 1. Activities & Streams (6 tools)

  • 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 directly to an activity.

๐Ÿ‘ค 2. Athlete Biometrics & Zones (2 tools)

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

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

๐Ÿงฎ 3. Calculator & Matrix (3 tools)

  • calculate_vdot: Compute Jack Daniels VDOT & VOโ‚‚max from race or time-trial results.

  • calculate_pace_zones: Compute 5 pace training zones (Easy, Marathon, Threshold, Interval, Repetition).

  • calculate_nsa_matrix: Generate Norwegian Singles Copeland interval matrix (Fast, Medium, Long) with target paces and power.

๐Ÿ”ฌ 4. Physiology & Endurance Intelligence (9 tools)

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

  • calculate_taper_plan: Generate structured tapering schedule (A/B/C Taper) for peak freshness.

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

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

  • calculate_rhr_baseline: Compute dynamic resting heart rate (RHR) baseline range and rolling averages from historical readings.

  • calculate_race_fueling: Compute carbohydrate intake targets (g/h), gel schedules, and hydration limits.

  • diagnose_aerobic_base: Diagnose Aerobic Deficiency Syndrome (ADS) via Uphill Athlete 10% Rule & Horwill's Rule.

  • calculate_hadd_zones: Calculate John Hadd absolute HR training zones and Sub-T baseline.

  • estimate_aerobic_threshold: Estimate Aerobic Threshold (AeT / VT1) from Max HR and drift telemetry.

โš–๏ธ 5. Training Load & Periodization (2 tools)

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

  • calculate_weekly_budget: Calculate safe weekly training distance and duration allocation based on 42-day rolling history.

๐Ÿ“… 6. Calendar & Structured Events (9 tools)

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

  • get_event_by_id: Get detailed event data by ID.

  • delete_event: Remove calendar events by ID.

  • add_or_update_planned_workout: Create or update planned workout events.

  • add_or_update_note: Add text notes to calendar dates.

  • get_workout_library: Search workout template library.

  • get_workout_by_id: Get workout template details.

  • create_running_workout: Validate and publish structured running workouts to Intervals.icu calendar using Text DSL.

  • generate_weekly_plan: Generate structured multi-day weekly training plans based on volume targets and periodization block.

โš™๏ธ 7. Custom Items (5 tools)

  • get_custom_items: List custom charts, fields, or interval fields.

  • get_custom_item_by_id: Retrieve specific custom item.

  • create_custom_item: Create a new custom item.

  • update_custom_item: Update custom item metadata.

  • delete_custom_item: Remove a custom item.

๐Ÿ‘Ÿ 8. Gear (1 tool)

  • get_gear_list: List registered running shoes and gear with accumulated mileage (cached 30m).

๐Ÿ“ˆ 9. Power Curves (1 tool)

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

๐Ÿ’š 10. Wellness & Fitness Time-Series (2 tools)

  • 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 (120 tests)
pnpm test

# Build TypeScript
pnpm run build

# Watch mode during development
pnpm exec vitest

Includes 120 unit tests across 20 test files covering API client auto-retry on HTTP 429, LRU TTL caching, Jack Daniels VDOT math, Copeland interval matrix, John Hadd physiology & ADS diagnostic engine, race prediction, cardiac drift analysis, recovery scoring, race fueling, and workout DSL validation.


๐Ÿ“„ License

This project is licensed under the MIT License ยฉ intervals-icu-mcp contributors.

Available Tools

19 tools
add_activity_messageAdd Activity MessageA

Tambahkan catatan/komentar baru ke sebuah aktivitas.

Inputs: content (required), activityId (required), apiKey.

add_or_update_noteAdd or Update NoteA

Buat atau update catatan teks biasa (kategori NOTE) di kalender Intervals.icu.

Inputs: name (required), description (required), color, apiKey, +3 more.

add_or_update_planned_workoutAdd or Update Planned WorkoutA

Buat atau update planned workout (event kalender kategori WORKOUT) di Intervals.icu. Kirim event_id untuk update, kosongkan untuk membuat baru. workoutDoc opsional untuk mendefinisikan struktur steps (warmup/interval/cooldown, target power/hr/pace, dll โ€” ikuti format workout builder Intervals.icu).

Inputs: name (required), workoutType (required), apiKey, eventId, +5 more.

create_custom_itemCreate Custom ItemA

Buat custom item baru (chart/field/zones) untuk seorang athlete. Catatan enum penting: field 'type' di dalam content untuk INPUT_FIELD/ACTIVITY_FIELD harus 'numeric' | 'text' | 'select' (bukan 'number'); field 'aggregate' harus MIN|SUM|MAX|AVERAGE (bukan AVG).

Inputs: name (required), itemType (required), apiKey, content, +3 more.

delete_custom_itemDelete Custom ItemB

Hapus satu custom item berdasarkan ID.

Inputs: itemId (required), apiKey, athleteId.

delete_eventDelete EventB

Hapus satu event kalender berdasarkan event ID.

Inputs: eventId (required), apiKey, athleteId.

get_activitiesGet ActivitiesB

Ambil daftar aktivitas latihan seorang athlete dari Intervals.icu dalam rentang tanggal tertentu.

Inputs: limit, apiKey, endDate, athleteId, +1 more.

get_activity_detailsGet Activity DetailsB

Ambil detail lengkap satu aktivitas berdasarkan activity ID.

Inputs: activityId (required), apiKey.

get_activity_intervalsGet Activity IntervalsA

Ambil data interval/lap (power, HR, pace per segmen) dari satu aktivitas.

Inputs: activityId (required), apiKey.

get_activity_messagesGet Activity MessagesB

Ambil catatan/komentar (messages) pada satu aktivitas.

Inputs: activityId (required), apiKey.

get_activity_streamsGet Activity StreamsA

Ambil data time-series (streams) dari satu aktivitas, misalnya power, heart rate, cadence, altitude, distance, velocity.

Inputs: activityId (required), apiKey, streamTypes.

get_athlete_power_curvesGet Athlete Power CurvesA

Ambil power curve (best power per durasi, dalam watt) seorang athlete untuk musim ini/lalu, dan/atau rentang tanggal custom.

Inputs: apiKey, endDate, athleteId, durations, +5 more.

get_custom_item_by_idGet Custom Item By IDA

Ambil detail satu custom item berdasarkan ID.

Inputs: itemId (required), apiKey, athleteId.

get_custom_itemsGet Custom ItemsA

Ambil daftar custom item (custom chart, field, zones, dll) milik seorang athlete.

Inputs: apiKey, athleteId.

get_event_by_idGet Event By IDB

Ambil detail satu event kalender berdasarkan event ID.

Inputs: eventId (required), apiKey, athleteId.

get_eventsGet EventsA

Ambil daftar event kalender (planned workout, race, note) dalam rentang tanggal.

Inputs: apiKey, endDate, athleteId, startDate.

get_gear_listGet Gear ListB

Ambil katalog gear (sepeda, sepatu, dll) beserta statistik dasarnya untuk seorang athlete.

Inputs: apiKey, athleteId.

get_wellness_dataGet Wellness DataA

Ambil data wellness harian athlete (training metrics, HRV, resting HR, sleep, subjective scores, dll) dalam rentang tanggal tertentu.

Inputs: apiKey, endDate, athleteId, startDate.

update_custom_itemUpdate Custom ItemA

Update custom item yang sudah ada. Hanya field yang diisi yang akan dikirim.

Inputs: itemId (required), name, apiKey, content, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.7/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action. Activity-related tools are separated by data granularity (list, details, intervals, streams, messages), and event/custom item tools follow clear CRUD patterns. No two tools appear to serve the same purpose.

    Naming Consistency5/5

    All tools use a consistent verb_noun pattern in snake_case. Retrieval uses get_, creation uses add_/create_, updates use update_/add_or_update_, and deletion uses delete_. Minor variation like add_or_update_ is predictable.

    Tool Count4/5

    At 19 tools, this is above the ideal 3-15 range but appropriate for the broad scope covering activities, events, wellness, gear, power curves, and custom items. The tools are grouped by domain and each is justified; still, a few could be consolidated, so not a perfect 5.

    Completeness4/5

    Core workflows are well covered: activities have read and message addition, events have full CRUD, and custom items have full CRUD. Gaps include no activity update/delete, no gear management, and no wellness update, but these may be outside the API's intended scope or rare needs.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Adaptive running coach MCP server โ€” training data, plans, and recovery for AI assistants.

      https://api.coachicarus.com/mcp
    • Intervals.icu MCP server for ChatGPT, Claude and any AI agent: list activities, get activity with intervals, list wellness, list calendar events, create planned workout, update planned workout, delete calendar event and log daily wellness in your own Intervals.icu account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Intervals.icu yourself; Cotlet does not store your password and you need no Intervals.icu API key. About the official Intervals.icu API: Yes, Intervals.icu has a public REST API (checked 6 Nov 2026). You generate a personal API key under Developer Settings for your own data, and apps for many users use OAuth. Setup and FAQ: https://cotlet.dev/integrations/intervals-icu-api-mcp-server

    • Connect Intervals.icu to Claude and ChatGPT: read training, plan workouts. Training never stored.

      https://thresholdlink.app/mcp
    • tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).

      https://tri-train.com/api/mcp

    Related MCP Servers