Intervals.icu MCP Server

POST a new note or comment on a specific activity (singular = WRITE).

Use when the user wants to leave a note on one of their activities: "add a note to this ride that I felt strong", "comment on yesterday's run", "leave a training note saying...". Attributed to the authenticated user. To READ existing notes use icu_get_activity_messages (plural).

Recompute training load, zones, and derived metrics on HISTORICAL activities using the current sport settings.

Different from update_sport_settings (which just stores new values). Use after changing FTP/FTHR/pace to backfill chart math.

Schedule an entire training plan (workout-library folder) onto the athlete's calendar starting on a chosen date.

Use after icu_get_workout_library to find a plan's folder_id. Different from icu_create_event / icu_bulk_create_events (which build new events) and from icu_duplicate_events (which copies existing).

Create MANY new calendar events in a single batch call (more efficient than looping create_event).

Accepts a JSON array of event objects, each shaped like an icu_create_event payload. For copying existing events forward use icu_duplicate_events instead — that reuses payloads rather than taking new fields. See intervals-icu://event-categories and intervals-icu://workout-syntax for the referenced enums and DSL.

Batch-create manual activities (no device upload) with UPSERT on external_id.

Existing activities with a matching external_id (set by the same OAuth app) are updated; activities without an external_id are always created new.

Delete MANY calendar events in a single batch call. Destructive — cannot be undone.

In safe delete mode (default), the call partitions the input list into deleted (future) and skipped (past or undated) and returns both. INTERVALS_ICU_DELETE_MODE=full disables the partition.

Create a custom addition to the user's Intervals.icu account.

Use when the user says things like: "add a custom field for RPE", "create a custom power zone set", "add a chart for monthly distance". Match the user's intent to the right item_type (see that param's description). For the content schema per item_type, read intervals-icu://custom-item-schemas.

Create ONE new calendar event from scratch.

For two or more events in a single call, prefer icu_bulk_create_events over a loop. For copying existing events forward in time (repeating a workout for N weeks), use icu_duplicate_events — that tool reuses an existing event's payload instead of taking new fields.

For category guidance and the training_availability enum, read the intervals-icu://event-categories resource. For structured WORKOUT events, put workout-syntax text in description — see intervals-icu://workout-syntax.

Create a new gear item for tracking equipment usage and maintenance (bikes, shoes, trainers, etc.).

Create a maintenance reminder for a gear item, triggered by distance, time, or both.

Create a per-sport threshold record with outdoor/indoor FTP, FTHR, pace, or swim settings.

Permanently delete ONE calendar event by ID. Destructive — cannot be undone.

In safe delete mode (default), past events are refused and reported in the skipped envelope with a hint about INTERVALS_ICU_DELETE_MODE=full. Returns a deleted / skipped envelope either way.

Permanently delete a gear item and its maintenance reminders. Activities that used this gear are not affected.

Download the original activity file.

Downloads the ORIGINAL uploaded file (FIT, TCX, or GPX — whatever the device produced). Different from download_fit_file (forces FIT conversion) and download_gpx_file (forces GPX conversion). If output_path is set the file is saved there; otherwise the response embeds base64 content.

Download activity converted to FIT format (Garmin / most training platforms). Different from download_activity_file (original upload format) and download_gpx_file (GPX format).

Download activity converted to GPX format (GPS devices, mapping software). Different from download_activity_file (original upload format) and download_fit_file (FIT format).

COPY existing events forward in time by N weeks.

Use when the user says "repeat this workout for the next 4 weeks", "duplicate Monday's run on the next 3 Mondays". Reuses the existing events' payloads — different from icu_create_event / icu_bulk_create_events, which both build NEW events from scratch.

Fetch the activities chronologically before and after a reference activity (N each side).

Use for "what did I do around this race?", training-context queries, progression comparisons.

List activities within an EXPLICIT date window (oldest..newest) — LIGHT summary per item.

Unlike icu_get_recent_activities (anchored to today and capped at 100), this targets an arbitrary historical window and is bounded only by limit. Use for "all my runs from June to November 2025", reconstructing training history, or finding the oldest activity in a period. Dates are YYYY-MM-DD. Results are newest-first; if a window holds more than limit items, the oldest are dropped first, so widen limit (or narrow the window) to reach the very oldest.

Fetch the headline SUMMARY of one activity — name, sport, date, distance, duration, training load, weather, plus all top-level metrics in a single JSON blob.

Use for "how was my ride?", "tell me about activity X". For lap-by-lap or per-interval breakdown use icu_get_activity_intervals; for second-by-second time-series use icu_get_activity_streams.

Fetch the per-LAP / per-interval breakdown of one activity — each segment with its target, actual power/HR/pace, and type (warm-up / work / rest / cool-down).

Use for workout-compliance analysis, lap-by-lap review, "did I hit my intervals?". For headline summary metrics use get_activity_details; for raw second-by-second data use get_activity_streams.

Read the notes and comments attached to a specific activity (plural = READ).

Use when the user asks: "what did my coach say about that ride?", "show me the comments on yesterday's run", "any feedback on this workout?". Returns every message in chronological order with author, content, timestamp, and seen-flag. To POST a new message use icu_add_activity_message (singular = WRITE).

Fetch RAW per-sample time-series of one activity — second-by-second arrays for power, HR, cadence, speed, altitude, GPS, temperature, grade, etc.

Heavy payload. Use only when you need the underlying signal for visualization or custom analysis. Most "how was my ride?" questions are better answered by get_activity_details (summary metrics) or get_activity_intervals (per-lap breakdown).

Stream-type filter accepts any of: watts, heartrate, cadence, velocity_smooth, altitude, distance, time, latlng, temp, moving, grade_smooth.

Read the Annual Training Plan (ATP) on the calendar — weekly load targets (TSS), Base/Build/Peak phases, and ATP week notes.

Use when the user asks: "what's my weekly TSS target?", "what training phase am I in?", "show my periodization plan", "when are my recovery weeks?", "what's the note on this training week?". Defaults to a 365-day forward window so the full ATP is returned; pass a smaller days_ahead/days_back when the user asks about a specific month or week. NOT individual planned workouts (icu_get_upcoming_workouts), NOT all calendar entries (icu_get_calendar_events), NOT workout-library plan folders (icu_get_workout_library / icu_apply_training_plan).

Get an athlete's profile — sport settings (outdoor/indoor FTP, FTHR, pace) and current CTL/ATL/TSB.

Defaults to the authenticated athlete; coaches can pass athlete_id to read one of their managed athletes instead.

Find the top-N peak efforts WITHIN a single activity for a given stream + target duration or distance.

Different from get_*_curves (which span many activities). Useful for "what was my best 20-min power on this ride?" or "show my top 5k splits in this run." Requires at least one of duration or distance.

Fetch ALL calendar entries in a date window — workouts, notes, races, goals, life-event blocks.

Use for "what's on my calendar?", "show this week", broad calendar queries. For just the planned WORKOUT entries (filtered) use icu_get_upcoming_workouts. For one specific event by ID use get_event.

Fetch the full configuration of ONE custom addition by ID.

Use AFTER icu_get_custom_items has returned an ID when the user wants to inspect a specific chart/field/zone/panel — the content field here is the same as in the list, just focused on one item.

List the user's custom additions to their Intervals.icu account.

Use this when the user asks about THEIR OWN customizations: "show my custom charts", "list my custom fields", "what custom zones do I have", "what's on my dashboard", "do I have any custom activity panels".

Returns every custom item across all types in one call: custom charts (FITNESS_CHART, TRACE_CHART, ACTIVITY_CHART, ACTIVITY_HISTOGRAM, ACTIVITY_HEATMAP, ACTIVITY_MAP, ACTIVITY_PANEL, FITNESS_TABLE), custom data fields (INPUT_FIELD on wellness, ACTIVITY_FIELD on activities, INTERVAL_FIELD on intervals), custom ACTIVITY_STREAM definitions, and custom ZONES configurations. Each item has a type field so you can filter client-side if the user asked about a specific kind.

Do NOT use this for built-in zones, built-in fields, or athlete profile data — those have dedicated tools (icu_get_sport_settings, etc.).

Args: athlete_id: Athlete ID (uses configured default if not provided)

Returns: JSON string with the list of custom items and total count

Fetch ONE specific calendar event by ID — full details including description, workout structure, and metrics.

Fetch the Performance Management Chart time-series — daily CTL, ATL, and TSB.

Returns past history plus future projections from planned calendar workouts. Use for: "show my fitness chart", "CTL trend last 90 days", "projected form at end of my block", "what will my TSB be in 3 weeks". NOT for: today's training recommendations (icu_get_fitness_summary), HRV/sleep/ recovery trends (icu_get_wellness_data), or one day's full wellness record (icu_get_wellness_for_date).

Get an athlete's current fitness / fatigue / form snapshot — CTL, ATL, TSB, ramp rate, with interpretation and training recommendations.

Use for "how's my form?", "am I overtrained?", training-status checks. Defaults to the authenticated athlete; coaches can pass athlete_id to read one of their managed athletes instead.

Time-in-zone DISTRIBUTION of grade-adjusted pace (GAP) within a single activity — elevation-normalized.

Use for trail running where raw pace is misleading. For raw (non- elevation-normalized) pace use icu_get_pace_histogram.

List all gear items with usage stats (distance, time, activity count) and maintenance reminders.

Fetch the HR-vs-duration curve — best (highest) sustained HR across durations from 5s up to 1h, aggregated over the chosen window.

Use for cardiovascular-fitness trends and HR-zone calibration. For time-in-zone *distribution* within a single activity, use get_hr_histogram instead.

Time-in-zone DISTRIBUTION of heart rate within a single activity (histogram buckets, time per bucket).

Different from icu_get_hr_curves (best efforts across many activities). Use for cardiovascular load breakdown and HR-zone time-in-zone.

Fetch the pace-vs-duration curve — best (fastest) sustained pace across durations from 5s up to 1h, aggregated over the chosen window.

Use for run/swim fitness trends and race-time predictions. Pass use_gap=True to normalize for hills via Grade-Adjusted Pace. For time-in-zone *distribution* within a single activity, use get_pace_histogram (or get_gap_histogram) instead.

Time-in-zone DISTRIBUTION of pace within a single running activity (histogram buckets, time per bucket).

Different from icu_get_pace_curves (best efforts across many activities). Use for pace-distribution / consistency analysis. For elevation- normalized pace use icu_get_gap_histogram.

Fetch the power-vs-duration curve — best (highest) sustained watts across durations from 5s up to 1h, aggregated over the chosen window.

Use for FTP estimation, peak-power tracking, strengths/weaknesses across duration profiles. For time-in-zone *distribution* within a single activity, use icu_get_power_histogram instead.

Time-in-zone DISTRIBUTION of power within a single activity (histogram buckets, time per bucket).

Different from icu_get_power_curves (best efforts across many activities). Use for "how was my workout intensity distributed?", training-zone breakdown.

List the athlete's most recent activities (default last 30 days) — LIGHT summary per item (distance, duration, power, HR, training load).

Use for "what have I done recently?", "show last week's rides". For one specific activity by ID use icu_get_activity_details; to search by name/tag use icu_search_activities.

Get all per-sport thresholds — outdoor/indoor FTP, FTHR, running pace, and swim threshold.

Fetch only the planned WORKOUT entries from the upcoming calendar (filters out notes, races, goals).

Use for "what's my next workout?", "what training is planned". For every calendar entry type use icu_get_calendar_events.

Fetch wellness records over a RANGE of recent days (default last 7).

Use for trends, weekly summaries, "how has my sleep been this week?", recovery curves. For PMC/fitness chart CTL/ATL/TSB series use icu_get_fitness_chart. For a single specific date use icu_get_wellness_for_date instead — this tool always returns a multi-day list.

Fetch the wellness record for ONE specific date.

Use when the user names a date — "show my HRV for Monday", "wellness on 2026-03-15", "how did I sleep last Thursday?". For ranges, weeks, or trends use icu_get_wellness_data.

List all workout-library folders + training plans the athlete has access to (personal, shared, and followed plans).

Each folder ID can be passed to icu_get_workouts_in_folder to see its contents, or to icu_apply_training_plan to schedule it onto the calendar.

List the workouts stored in one specific library folder or training plan — name, type, structure, training load, intensity factor.

List the athletes this account can access — the caller plus anyone they follow or coach.

Call this FIRST whenever a request concerns someone other than the default athlete, to resolve a name to the athlete_id that other tools take. Returns each athlete's access level, so you know before calling whether a write will be permitted.

Search activities by name or tag, returning a LIGHT result list — id, name, type, date, distance, time only.

Use this first for "find my X" queries. Only escalate to search_activities_full when you specifically need power, HR, training load, or intensity-factor data on the matches (heavier payload).

Search activities by name or tag, returning FULL Activity objects with power, HR, training load, intensity factor, normalized power, weather — every metric per result.

Heavy payload. Use only when the lighter search_activities won't tell you what you need (e.g. "find my threshold rides with NP above 250W").

Search intervals ACROSS ALL the athlete's activities (cross-activity).

Different from icu_get_activity_intervals (single-activity). Use to track progress on a workout type ("all my threshold intervals over the last year") or find comparable historical sessions. Returns the activities containing matching intervals, each with an interval_summary like "2x 8m 162w" (reps x duration at target).

Update an existing activity's metadata (name, type, trainer flag, RPE, feel, etc.).

Only fields you pass are sent; everything else stays unchanged.

Upload raw time-series streams (power, HR, cadence, etc.) onto an existing activity. Destructive — overwrites existing stream data.

Accepts JSON array or CSV. Different from get_activity_streams (READ).

Modify an existing custom chart/field/zones/panel.

Use when the user wants to change one of their existing customizations: "rename my custom field", "make this chart public". Usually need icu_get_custom_items first to find the right item_id. Only fields you pass are sent — others are left unchanged. For content schema, see intervals-icu://custom-item-schemas.

Update an existing calendar event.

Only fields you pass are sent — other fields remain unchanged. For category and training_availability semantics, see intervals-icu://event-categories. For WORKOUT description syntax, see intervals-icu://workout-syntax.

Update an existing gear item. Only fields you pass are sent.

Update an existing gear maintenance reminder. Only fields you pass are sent.

Update an existing per-sport threshold record (outdoor/indoor FTP, FTHR, pace, swim).

Upsert wellness data for ONE specific date — creates the record if missing, otherwise updates the fields you pass.

Only provided fields are sent. Subjective scales (fatigue, soreness, stress, mood, motivation, injury) are 1-5. Pass locked=True to stop device sync from overwriting manual entries. Writes to the authenticated athlete unless athlete_id names a managed athlete.