io.github.hhopke/intervals-icu-mcp

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).

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.

Save MANY new reusable workouts into LIBRARY folders or plans in one call — e.g. filling out a training plan. Each item is shaped like an icu_create_workout call. Nothing lands on the calendar: for dated calendar workouts use icu_bulk_create_events, and to schedule a finished plan use icu_apply_training_plan.

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.

Hide/reveal or lock/unlock MANY planned WORKOUT calendar events at once. Sets the web UI's "Hide from athlete" and "Athlete cannot edit" checkboxes — e.g. build a training block ahead of time, hide it, and reveal it week by week, or lock key sessions. Only the flags you pass are changed. Only WORKOUT events are touched: notes, races and targets are reported under `skipped`. IDs are calendar event IDs (from icu_get_calendar_events / icu_get_upcoming_workouts), not workout-library IDs. For one event use icu_update_event.

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.

Save ONE new reusable workout into a LIBRARY folder or training plan — it does not go on the calendar. To schedule a workout on a date use icu_create_event. For two or more library workouts use icu_bulk_create_workouts; to change a saved one use icu_update_workout. Make a new folder or plan with icu_create_workout_folder, and put a plan's workouts on the calendar with icu_apply_training_plan.

Create a new LIBRARY folder or training PLAN to hold workouts — not a calendar item. Pass the returned id as folder_id to icu_create_workout or icu_bulk_create_workouts. To browse existing folders use icu_get_workout_library.

DELETE one of your own notes from an activity. Use when the user wants a note removed: "delete my comment on that run", "remove the note I left yesterday". Only the author's own notes can be deleted. Intervals.icu keeps a "(deleted)" placeholder in the thread. Returns the deleted text so it can be re-posted with icu_add_activity_message if needed (the original timestamp is lost).

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.

Permanently delete ONE workout from the LIBRARY. Destructive — cannot be undone. Removes the library workout only; calendar events are separate records deleted with icu_delete_event. Confirm with the user before calling if unsure.

Permanently delete ONE library folder or training plan AND every workout in it. Destructive — cannot be undone. Calendar events already applied from a plan stay on the calendar (delete those with icu_delete_event); to remove a single library workout use icu_delete_workout. In `safe` delete mode (default), a folder that still holds workouts is refused and reported in the `skipped` envelope. Confirm with the user before calling if unsure.

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. Deleted notes stay in the thread as a "(deleted)" placeholder with a `deleted` timestamp. 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, raw_heartrate, fixed_heartrate. `latlng` comes back as [lat, lng] pairs (null where the sample has no GPS fix). `left_right_balance` (dual-sided power meters) is the RIGHT pedal's share of power in percent (FIT convention), not the left's: a stream averaging 48 means L 52% / R 48%. The response adds a `stream_notes` entry saying so whenever the stream is returned. `heartrate` is CORRECTED data: Intervals.icu replaces readings above the athlete's configured max HR with an interpolated line at import, so it can never exceed that setting. `raw_heartrate` is the uncorrected trace and is the only way to see a genuine new max that was clipped away — the platform never raises the setting on its own. Request it explicitly; it is not in the default set.

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. Also returns the free-text athlete notes (Markdown) when set; change them with icu_update_athlete_notes. 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.).

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. For the athlete's HR zones and max HR, call icu_get_sport_settings — this tool does not return zone bands, and its peak_hr_bpm is the top of this curve, which Intervals.icu has already clipped to the configured max HR at import. 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 and W/kg across durations from 5s up to 6h, aggregated over the chosen window. Use for FTP estimation, peak-power tracking, durability, strengths/weaknesses across duration profiles. Includes fitted power models (CP, W', Pmax, FTP), the VO2max estimate and MAP when Intervals.icu provides them. Pick ONE window: days_back, time_period, start_date/end_date, season, or periods (to compare several, e.g. ['s0', 's1', 'all']). Default is the last 90 days. 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.

List the athlete's training SEASONS defined in Intervals.icu (name, start, end, curve ID). Use for "which seasons do I have?", or before comparing seasons: pass a season's curve_id ('s0' = current, 's1' = previous, ...) to icu_get_power_curves. A season runs until the day before the next one starts; the newest season is open-ended.

Get per-sport thresholds and the athlete's configured power/HR/pace zones. Returns outdoor/indoor FTP, FTHR, max HR, running pace and swim threshold, plus the zone sets configured in Intervals.icu (HR zones in bpm, power zones as %FTP, pace zones as % of threshold pace) with their names. This is the ONLY source of the athlete's real zones. Intervals.icu derives them from the threshold (unless set explicitly) and stamps them into every activity at import, so time-in-zone, HRSS and TSS are all computed from these — reasoning about zones from any other number puts the answer at odds with the athlete's own charts. Zones are not derived from curve data.

Fetch the planned WORKOUT entries dated on the upcoming CALENDAR (filters out notes, races, goals) — these are calendar EVENTS, not workout-library templates. Use for "what's my next workout?", "what training is planned". Each `id` is a calendar event ID: pass it to icu_get_event / icu_update_event / icu_delete_event, never to the icu_*_workout library tools. For every calendar entry type use icu_get_calendar_events; for reusable templates stored in the library use icu_get_workouts_in_folder. hide_from_athlete / athlete_cannot_edit appear only when set (change them with icu_bulk_update_event_access).