Skip to main content
Glama
Intervals.icu MCP Server

Intervals.icu MCP Server

by farhoodlabs

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
API_KEYNoAn Intervals.icu API key (Settings → API on intervals.icu). Used in local/single-user fallback mode.
ATHLETE_IDNoYour athlete id, e.g. i12345 (from the intervals.icu URL). Must match i?\d+.
MCP_ISSUERNoOAuth token issuer.
DATABASE_URLNoAsync Postgres DSN (postgresql+asyncpg://…) for the shared user store.
FASTMCP_HOSTNoHTTP bind host.
FASTMCP_PORTNoHTTP bind port.
MCP_JWKS_URINoThe JWKS endpoint URL.
MCP_RESOURCENoThe /mcp resource URL.
MCP_TRANSPORTNoTransport type: stdio, sse, or http/streamable-http.stdio
FASTMCP_LOG_LEVELNoLog level for FastMCP.
INTERVALS_ENC_KEYNoBase64-encoded 32-byte AES-256-GCM key used to encrypt stored API keys.
MCP_JSON_RESPONSENoHTTP tuning flag (true/false).
MCP_STATELESS_HTTPNoHTTP tuning flag (true/false).
INTERVALS_API_BASE_URLNoBase URL for the Intervals.icu API.https://intervals.icu/api/v1

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
get_gear_listA

Get the gear catalog (bikes, shoes, etc.) for the signed-in athlete from Intervals.icu.

Returns one line per gear item with id, type, name, and basic stats.
The result is cached for the MCP process lifetime; pass refresh=True to
re-fetch.

Args:
    refresh: If True, bypass the cache and re-fetch from the API (default False)
get_activitiesB

Get a list of activities for the signed-in athlete from Intervals.icu

Args:
    start_date: Start date in YYYY-MM-DD format (optional, defaults to 30 days ago)
    end_date: End date in YYYY-MM-DD format (optional, defaults to today)
    limit: Maximum number of activities to return (optional, defaults to 10)
    include_unnamed: Whether to include unnamed activities (optional, defaults to False)
get_activity_detailsC

Get detailed information for a specific activity from Intervals.icu

Args:
    activity_id: The Intervals.icu activity ID
get_activity_intervalsB

Get interval data for a specific activity from Intervals.icu

This endpoint returns detailed metrics for each interval in an activity, including power, heart rate,
cadence, speed, and environmental data. It also includes grouped intervals if applicable.

Args:
    activity_id: The Intervals.icu activity ID
get_activity_streamsA

Get stream data for a specific activity from Intervals.icu

This endpoint returns time-series data for an activity, including metrics like power, heart rate,
cadence, altitude, distance, temperature, and velocity data.

Args:
    activity_id: The Intervals.icu activity ID
    stream_types: Comma-separated list of stream types to retrieve (optional, defaults to all available types)
                 Available types: time, watts, heartrate, cadence, altitude, distance,
                 core_temperature, skin_temperature, velocity_smooth
get_activity_messagesA

Get messages (notes/comments) for a specific activity from Intervals.icu

Args:
    activity_id: The Intervals.icu activity ID
add_activity_messageB

Add a message (note/comment) to an activity on Intervals.icu

Args:
    activity_id: The Intervals.icu activity ID
    content: The message text to add
search_activitiesB

Search the athlete's activities by name/keyword.

Args:
    query: Search text matched against activity name/description (required).
    limit: Maximum number of results to return (default 20).
get_activity_best_effortsB

Get the best efforts (peak values over windows) for an activity.

Args:
    activity_id: The Intervals.icu activity ID.
    stream: Data stream to analyze — e.g. "watts", "heartrate", "pace" (default "watts").
    duration: Optional window duration in seconds to target.
    distance: Optional window distance in meters to target.
    count: Optional maximum number of efforts to return.
get_activity_interval_statsA

Compute aggregate stats for an index range of an activity's data streams.

start_index/end_index are positions in the activity's streams (as seen in the
streams or interval output). This computes metrics for that slice — it does NOT
list the activity's own intervals (use get_activity_intervals for that).

Args:
    activity_id: The Intervals.icu activity ID.
    start_index: Start position in the activity streams (required).
    end_index: End position in the activity streams (required, > start_index).
get_eventsA

Get events for an athlete from Intervals.icu

Args:
    start_date: Start date in YYYY-MM-DD format (optional, defaults to today)
    end_date: End date in YYYY-MM-DD format (optional, defaults to 30 days from today)
get_event_by_idC

Get detailed information for a specific event from Intervals.icu

Args:
    event_id: The Intervals.icu event ID
delete_eventC

Delete event for an athlete from Intervals.icu Args: event_id: The Intervals.icu event ID

delete_events_by_date_rangeC

Delete events for an athlete from Intervals.icu in the specified date range.

Args:
    start_date: Start date in YYYY-MM-DD format
    end_date: End date in YYYY-MM-DD format
add_or_update_eventA

Post event for an athlete to Intervals.icu this follows the event api from intervals.icu If event_id is provided, the event will be updated instead of created.

Many arguments are required as this MCP tool function maps directly to the Intervals.icu API parameters.

Args:
    event_id: The Intervals.icu event ID (optional, will use event_id from .env if not provided)
    start_date: Start date in YYYY-MM-DD format (optional, defaults to today)
    name: Name of the activity
    workout_doc: steps as a list of Step objects (optional, but necessary to define workout steps)
    workout_type: Workout type (e.g. Ride, Run, Swim, Walk, Row)
    moving_time: Total expected moving time of the workout in seconds (optional)
    distance: Total expected distance of the workout in meters (optional)

Example:
    "workout_doc": {
        "description": "High-intensity workout for increasing VO2 max",
        "steps": [
            {"power": {"value": 80, "units": "%ftp"}, "duration": 900, "warmup": true},
            {"reps": 2, "text": "High-intensity intervals", "steps": [
                {"power": {"value": 110, "units": "%ftp"}, "distance": 500, "text": "High-intensity"},
                {"power": {"value": 80, "units": "%ftp"}, "duration": 90, "text": "Recovery"}
            ]},
            {"power": {"value": 80, "units": "%ftp"}, "duration": 600, "cooldown": true},
            {"text": ""}
        ]
    }

Step properties:
    distance: Distance of step in meters
        {"distance": 5000}
    duration: Duration of step in seconds
        {"duration": 1800}
    power/hr/pace/cadence: Define step intensity
        Percentage of FTP: {"power": {"value": 80, "units": "%ftp"}}
        Absolute power: {"power": {"value": 200, "units": "w"}}
        Heart rate: {"hr": {"value": 75, "units": "%hr"}}
        Heart rate (LTHR): {"hr": {"value": 85, "units": "%lthr"}}
        Cadence: {"cadence": {"value": 90, "units": "cadence"}}
        Pace by ftp: {"pace": {"value": 80, "units": "%pace"}}
        Pace by zone: {"pace": {"value": 2, "units": "pace_zone"}}
        Zone by power: {"power": {"value": 2, "units": "power_zone"}}
        Zone by heart rate: {"hr": {"value": 2, "units": "hr_zone"}}
    Ranges: Specify ranges for power, heart rate, or cadence:
        {"power": {"start": 80, "end": 90, "units": "%ftp"}}
    Ramps: Instead of a range, indicate a gradual change in intensity (useful for ERG workouts):
        {"ramp": true, "power": {"start": 80, "end": 90, "units": "%ftp"}}
    Repeats: include the reps property and add nested steps
        {"reps": 3,
         "steps": [
            {"power": {"value": 110, "units": "%ftp"}, "distance": 500, "text": "High-intensity"},
            {"power": {"value": 80, "units": "%ftp"}, "duration": 90, "text": "Recovery"}
        ]}
    Free Ride: Include freeride to indicate a segment without ERG control, optionally with a suggested power range:
        {"freeride": true, "power": {"value": 80, "units": "%ftp"}}
    Comments and Labels: Add descriptive text to label steps:
        {"text": "Warmup"}

How to use steps:
- Set distance or duration as appropriate for step
- Use "reps" with nested steps to define repeat intervals (as in example above)
- Define one of "power", "hr" or "pace" to define step intensity
add_or_update_noteB

Add or update a plain text note (category NOTE) on the Intervals.icu calendar.

Args:
    name: Title of the note
    description: Plain text content of the note
    start_date: Date in YYYY-MM-DD format (optional, defaults to today)
    color: Color of the note (e.g. green, orange, red, blue)
    athlete_id: The Intervals.icu athlete ID (optional)
    api_key: The Intervals.icu API key (optional)
    event_id: The Intervals.icu event ID (optional, for updates)
get_custom_itemsB

Get custom items (charts, custom fields, zones, etc.) for an athlete from Intervals.icu

Args:
get_custom_item_by_idC

Get detailed information for a specific custom item from Intervals.icu

Args:
    item_id: The custom item ID
create_custom_itemB

Create a new custom item for an athlete on Intervals.icu

Args:
    name: Name of the custom item
    item_type: Type of custom item (e.g. FITNESS_CHART, TRACE_CHART, INPUT_FIELD, ACTIVITY_FIELD, INTERVAL_FIELD, ACTIVITY_STREAM, ACTIVITY_CHART, ACTIVITY_HISTOGRAM, ACTIVITY_HEATMAP, ACTIVITY_MAP, ACTIVITY_PANEL, ZONES)
    description: Description of the custom item (optional)
    content: Configuration content for the custom item as a dict (optional). Important enum values:
        - "type" field for INPUT_FIELD/ACTIVITY_FIELD: must be "numeric", "text", or "select" (NOT "number")
        - "aggregate" field: must be "MIN", "SUM", "MAX", or "AVERAGE" (NOT "AVG")
    visibility: Visibility setting: PRIVATE, FOLLOWERS, or PUBLIC (optional)
update_custom_itemA

Update an existing custom item for an athlete on Intervals.icu

Args:
    item_id: The custom item ID to update
    name: New name for the custom item (optional)
    item_type: New type for the custom item (optional)
    description: New description for the custom item (optional)
    content: New configuration content for the custom item as a dict (optional). Important enum values:
        - "type" field for INPUT_FIELD/ACTIVITY_FIELD: must be "numeric", "text", or "select" (NOT "number")
        - "aggregate" field: must be "MIN", "SUM", "MAX", or "AVERAGE" (NOT "AVG")
    visibility: New visibility setting: PRIVATE, FOLLOWERS, or PUBLIC (optional)
delete_custom_itemC

Delete a custom item for an athlete from Intervals.icu

Args:
    item_id: The custom item ID to delete
get_athlete_power_curvesA

Get power curves for an athlete from Intervals.icu.

Returns best power output for selected durations across specified time periods.
Uses FFT power computation. Power values are in watts.

Args:
    activity_type: Activity type (e.g. "Ride", "Run", "VirtualRide"). Default is "Ride".
    durations: Durations in seconds to include. Default is [5, 15, 30, 60, 120, 300, 600, 1200, 3600]
    indoor_outdoor: Filter by location — "indoor" or "outdoor". Omit for no filtering.
    start_date: Start date (YYYY-MM-DD) for custom date range curve. Must be used with end_date.
    end_date: End date (YYYY-MM-DD) for custom date range curve. Must be used with start_date.
    this_season: Include this season's curve (default True)
    last_season: Include last season's curve (default True)
    include_normalised: Include weight-normalised W/kg values (default True)
get_wellness_dataA

Get wellness data for the signed-in athlete from Intervals.icu.

By default returns standard wellness fields (training metrics, vitals, sleep,
subjective scores, etc.). Set include_all_fields=True to also include any
additional or custom fields configured by the user in Intervals.icu.

Args:
    start_date: Start date in YYYY-MM-DD format (optional, defaults to 30 days ago)
    end_date: End date in YYYY-MM-DD format (optional, defaults to today)
    include_all_fields: If True, include additional and custom fields beyond the standard set (optional, defaults to False)
update_wellnessA

Create or update the signed-in athlete's wellness record for a single day.

Writes nutrition, hydration, vitals, sleep, and subjective ratings to
Intervals.icu (PUT /athlete/{id}/wellness/{date}). Only the fields you pass are
sent; anything omitted is left untouched. To CLEAR an existing numeric value,
pass ``-1``. Set ``locked=True`` to stop Intervals.icu from overwriting these
values on its next sync from a connected device or app.

Args:
    date: Day to update in YYYY-MM-DD format (optional, defaults to today).
    weight: Body weight in kg.
    resting_hr: Resting heart rate in bpm.
    hrv: Heart rate variability (rMSSD).
    sleep_hours: Sleep duration in hours (stored by Intervals.icu as seconds).
        Pass -1 to clear.
    sleep_quality: Sleep quality rating, as used in the Intervals.icu app.
    calories_consumed: Energy intake in kcal.
    carbohydrates: Carbohydrate intake in grams.
    protein: Protein intake in grams.
    fat: Fat intake in grams.
    hydration_volume: Fluid intake volume, in your Intervals.icu units.
    hydration_score: Subjective hydration score, as used in the app.
    soreness: Subjective soreness rating, as used in the Intervals.icu app.
    fatigue: Subjective fatigue rating, as used in the Intervals.icu app.
    stress: Subjective stress rating, as used in the Intervals.icu app.
    mood: Subjective mood rating, as used in the Intervals.icu app.
    motivation: Subjective motivation rating, as used in the Intervals.icu app.
    injury: Injury level rating, as used in the Intervals.icu app.
    comments: Free-text note for the day.
    locked: If True, lock the record so device/app syncs won't overwrite it.
update_wellness_bulkA

Create or update multiple days of wellness data in a single call.

Writes to PUT /athlete/{id}/wellness-bulk. Each entry is a dict with a ``date``
(YYYY-MM-DD) plus any of the same fields as update_wellness: weight, resting_hr,
hrv, sleep_hours, sleep_quality, calories_consumed, carbohydrates, protein, fat,
hydration_volume, hydration_score, soreness, fatigue, stress, mood, motivation,
injury, comments, locked. Pass -1 to clear a numeric field. Every date is
validated up front — if any entry is invalid the whole batch is rejected, so
there are no partial writes.

Args:
    entries: List of per-day wellness dicts, each with a ``date`` and one or more fields.
get_training_readinessA

Assess training readiness from recent wellness data.

Synthesizes the athlete's recent wellness history into a readiness read:
HRV-guided (7-day rolling lnRMSSD vs baseline +/- smallest worthwhile change),
resting-HR and sleep trends, and subjective inputs (soreness/fatigue/stress/
mood/motivation). When there is too little data — notably fewer than ~2 weeks
of HRV — the verdict is withheld rather than guessed, and the report lists which
signals it could and could not use.

Args:
    days: How many days of history to analyze (default 45; minimum 14 is enforced).
get_athlete_profileA

Get the signed-in athlete's profile from Intervals.icu.

Returns identity and physiology basics (name, sex, weight, resting HR,
timezone, units, location). For per-sport FTP / zones / thresholds use
get_sport_settings instead.
get_sport_settingsA

Get the athlete's per-sport training settings (FTP, zones, thresholds).

These are the values that drive load, intensity and zone calculations across
Intervals.icu. Each record's "Settings ID" is the identifier update_sport_settings
uses to target a specific sport.

Args:
    sport: Optional sport type to filter by (e.g. "Ride", "Run"). Matches the
        record's sport types case-insensitively. If omitted, all sports are returned.
get_athlete_summaryA

Get a training-load summary (fitness/fatigue/form and totals) over a date range.

Note: the underlying endpoint's ``tags`` parameter filters *athletes* (a
coach-facing feature), not activities, so no tag filter is offered here.

Args:
    start_date: Start date in YYYY-MM-DD format (optional, defaults to 30 days ago).
    end_date: End date in YYYY-MM-DD format (optional, defaults to today).
update_sport_settingsA

⚠️ Change the athlete's training thresholds (FTP, LTHR, pace) for one sport.

These values drive ALL future load, intensity and zone calculations across
Intervals.icu. Do NOT call this speculatively — show the athlete the exact
old→new values and get their explicit approval first.

This is a confirmed write. On clients that support MCP elicitation you will be
prompted to approve the change; otherwise you MUST pass ``confirm=True`` after the
athlete has agreed. Without confirmation the tool refuses and returns the diff.

Args:
    settings_id: The sport-settings record ID (from get_sport_settings).
    ftp: New FTP in watts.
    indoor_ftp: New indoor FTP in watts.
    w_prime: New W' in joules.
    lthr: New lactate-threshold HR in bpm.
    max_hr: New max HR in bpm.
    threshold_pace: New threshold pace (in the sport's pace units).
    recalc_hr_zones: If True, ask Intervals.icu to recompute HR zones from the new LTHR/max HR.
    confirm: Set True to confirm the change on clients without elicitation support.
get_workoutsA

List the athlete's reusable workout library.

Filtering is applied client-side (the API returns the full library).

Args:
    folder_id: Optional folder ID to restrict results to one folder.
    sport_type: Optional sport type to filter by (e.g. "Ride", "Run").
get_workoutA

Get a single library workout's full structure (steps and targets).

Args:
    workout_id: The Intervals.icu workout ID.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.4/5.0

Scored across 32 tools

Disambiguation4/5

Most tools target clearly distinct resources and actions, and the activity sub-tools (details, streams, intervals, interval stats, best efforts) are differentiated by explicit descriptions. Minor ambiguity remains between add_or_update_event and add_or_update_note, since notes are event-like, and between the several activity-analytics tools.

Naming Consistency4/5

The set overwhelmingly uses consistent snake_case verb_noun naming such as get_activities, create_custom_item, delete_event, and update_wellness. Minor deviations like get_gear_list and the mixed update vs add_or_update conventions prevent a perfect score.

Tool Count3/5

At 32 tools, the surface is heavy, though the domain is broad and includes activities, events, wellness, custom items, workouts, athlete settings, and gear. Several activity-analysis tools are individually useful, but the overall count is borderline excessive and could benefit from consolidation.

Completeness4/5

Core lifecycle operations are well covered: activities can be listed, searched, inspected, and annotated; events have create/update/delete/range-delete; wellness supports read and write; and custom items have full CRUD. Gaps remain around workout-library CRUD and gear management beyond listing, but agents can still accomplish most training workflows.

Maintenance

ActivityInactive
ResponsivenessOutdated data