intervals-icu-mcp
This MCP server exposes Intervals.icu data and management tools for AI running-coach workflows.
Fetch activities by date range and get activity details, intervals, streams, and messages.
Add comments/notes to activities.
Retrieve daily wellness data such as HRV, resting HR, sleep, and training metrics.
Read, create/update, and delete calendar events.
Create or update planned workouts and plain-text calendar notes.
List gear and its accumulated mileage/statistics.
Retrieve athlete power curves for selected durations, seasons, activity type, and indoor/outdoor filters.
List and manage custom items (charts, fields, zones) with create, update, and delete operations.
Provides dual-engine integration with Garmin Connect health and training data, including Body Battery, HRV, sleep, and resting heart rate, combining it with Intervals.icu metrics for readiness scoring, recovery analysis, and AI running-coach recommendations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@intervals-icu-mcp What's my training load and sleep score for the last 7 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Intervals.icu MCP Server & AI Running Coach
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.0Package Manager:
pnpm(recommended),npm, oryarnIntervals.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 buildNote 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, rungit submodule update --init --recursive.
โ๏ธ Configuration
Retrieve your credentials from Intervals.icu Settings:
Scroll down to the Developer section.
Copy your API Key (e.g.
your_api_key_here).Note your Athlete ID (found in settings or profile URL, e.g.
i12345or useself).
Environment Variables
Variable | Required | Description |
| Yes | Your personal Intervals.icu API Key. |
| Optional | Default Athlete ID (default: |
| Optional | Base URL API Intervals.icu (default: |
๐ MCP Client Setup Guides
1. Claude Desktop
Add the following to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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 |
| 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. | |
| Post-run comprehensive evaluation: power telemetry (% CP), Copeland Sub-T intensity compliance, cardiac drift / aerobic decoupling (< 5%), and automated calendar feedback. | |
| 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. | |
| 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. | |
| Functional strength guide (22โ25 min) based on Stuart McGill Big 3 spinal protection and Running Anatomy kinetic chain strengthening (Soleus, Hamstrings, Hip Flexors). | |
| 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 vitestIncludes 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 toolsadd_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Adaptive running coach MCP server โ training data, plans, and recovery for AI assistants.
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.
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).
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceIntegrates Intervals.icu training data, wellness records, workouts, and calendar events with AI assistants through MCP tools.133 npm1MIT
- AlicenseAqualityCmaintenanceMCP server for Intervals.icu that enables AI assistants to manage athletic training data, including activities, calendar events, wellness metrics, and workout libraries.19Apache 2.0
- AlicenseAqualityDmaintenanceMCP server that connects Claude and ChatGPT to the Intervals.icu API, enabling retrieval and management of activities, events, wellness data, power curves, and custom items.21GPL 3.0
- FlicenseNot gradedqualityCmaintenanceMCP server for intervals.icu that reads training data (activities, wellness, calendar) and creates structured workouts on the calendar, which are pushed to devices like Garmin, Wahoo, Zwift, Coros, Suunto via the official API.-