Skip to main content
Glama
Intervals.icu MCP Server

Intervals.icu MCP Server

by farhoodlabs

Intervals.icu MCP Server

A self-hosted, multi-tenant Model Context Protocol (MCP) server that exposes the Intervals.icu API — activities, events, wellness, power curves, gear, and custom items — as MCP tools for Claude. It runs as a remote, OAuth-authenticated connector at https://intervalsicu.farhoodlabs.com/mcp, where each user's Intervals.icu API key and athlete id are stored encrypted and looked up per request from their OAuth identity.

This is a fork of the upstream single-tenant project (mvilanova/intervals-mcp-server), reworked for remote multi-user operation.

How it fits together

The system is three services on one Kubernetes host (intervalsicu.farhoodlabs.com), deployed via Flux GitOps and sharing one CloudNativePG Postgres database:

Service

Path

What it does

intervalsicu-mcp (this repo)

/mcp

The MCP server. Verifies OAuth JWTs and serves Intervals.icu data as MCP tools over streamable-HTTP.

intervalsicu-mcp-ui

/portal

Portal where users sign in (Google via Better Auth) and set their Intervals.icu credentials; admins approve accounts.

intervalsicu-mcp-auth

/api/auth

Better Auth OAuth 2.1 server: dynamic client registration (DCR), PKCE, EdDSA-signed JWTs + JWKS, Google login.

Connection flow: the Claude connector self-registers at the auth server (DCR), the user logs in with Google, and Claude receives a JWT access token whose audience is the /mcp URL. This server verifies that JWT against the auth server's JWKS and resolves the caller's stored Intervals.icu credentials by the token subject. A user who hasn't been approved or hasn't set credentials gets a friendly "account isn't ready" message.

Related MCP server: fitness-mcp-server

Connecting Claude

Add a custom remote connector in Claude pointing at:

https://intervalsicu.farhoodlabs.com/mcp

Name it without a dot — use intervals, not intervals.icu. Claude Desktop and mobile fail to load the tools if the connector name contains a dot. Claude handles registration and Google login for you. Your account must be approved in the portal and have Intervals.icu credentials set.

Available tools

get_activities, get_activity_details, get_activity_intervals, get_activity_streams, get_activity_messages, add_activity_message, get_events, get_event_by_id, add_or_update_event, delete_event, delete_events_by_date_range, get_wellness_data, get_athlete_power_curves, get_gear_list, get_custom_items, get_custom_item_by_id, create_custom_item, update_custom_item, delete_custom_item.

Local development

Requires Python 3.12+ and uv.

uv venv --python 3.12 && source .venv/bin/activate
uv sync --all-extras        # install with dev extras

uv run pytest               # tests (enforces a >=90% coverage gate)
ruff check .                # lint
mypy src tests              # type check

Run locally over stdio (single-user, using the env fallback credentials below):

python -m intervals_mcp_server.server

For local HTTP without OAuth, set MCP_TRANSPORT=http and leave MCP_ISSUER / MCP_RESOURCE / MCP_JWKS_URI unset — auth is disabled when those aren't all present, and tools use the API_KEY / ATHLETE_ID env fallback.

Environment variables

Local / single-user fallback (used only when there is no OAuth context):

  • API_KEY — an Intervals.icu API key (Settings → API on intervals.icu).

  • ATHLETE_ID — your athlete id, e.g. i12345 (from the intervals.icu URL). Must match i?\d+.

  • INTERVALS_API_BASE_URL — optional, defaults to https://intervals.icu/api/v1.

Multi-tenant / deployment:

  • DATABASE_URL — async Postgres DSN (postgresql+asyncpg://…) for the shared user store.

  • INTERVALS_ENC_KEY — base64-encoded 32-byte AES-256-GCM key used to encrypt stored API keys. Shared with the UI service so both read/write the same ciphertext.

  • MCP_ISSUER, MCP_RESOURCE, MCP_JWKS_URI — OAuth: token issuer, the /mcp resource URL, and the JWKS endpoint (an internal in-cluster URL, to bypass Cloudflare). Setting all three enables auth.

  • MCP_TRANSPORT — stdio (default), sse, or http/streamable-http. Deployment uses http.

  • MCP_STATELESS_HTTP, MCP_JSON_RESPONSE — HTTP tuning. The deployment sets both true (stateless + JSON) so the distributed connector can hit any replica; stateful/SSE breaks it.

  • FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL — HTTP bind + logging.

Deployment

Pushes to main trigger Gitea CI (.gitea/workflows/build.yaml): it runs the test suite with the coverage gate, then builds and pushes a container image to git.farh.net/farhoodlabs/intervalsicu-mcp. Flux reconciles the new image onto the cluster. Database migrations run as an Alembic (alembic upgrade head) initContainer before the server starts.

License

GNU General Public License v3.0 (inherited from the upstream project).

Available Tools

32 tools
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

Inputs: content (required), activity_id (required). Returns: result

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

Inputs: name (required), workout_type (required), distance, event_id, +3 more. Returns: result

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)

Inputs: name (required), description (required), color, event_id, +1 more. Returns: result

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)

Inputs: name (required), item_type (required), content, visibility, +1 more. Returns: result

delete_custom_itemC

Delete a custom item for an athlete from Intervals.icu

Args:
    item_id: The custom item ID to delete

Inputs: item_id (required). Returns: result

delete_eventC

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

Inputs: event_id (required). Returns: result

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

Inputs: end_date (required), start_date (required). Returns: result

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)

Inputs: limit, end_date, start_date, include_unnamed. Returns: result

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.

Inputs: activity_id (required), count, stream, distance, +1 more. Returns: result

get_activity_detailsC

Get detailed information for a specific activity from Intervals.icu

Args:
    activity_id: The Intervals.icu activity ID

Inputs: activity_id (required). Returns: result

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

Inputs: activity_id (required). Returns: result

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

Inputs: end_index (required), activity_id (required), start_index (required). Returns: result

get_activity_messagesA

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

Args:
    activity_id: The Intervals.icu activity ID

Inputs: activity_id (required). Returns: result

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

Inputs: activity_id (required), stream_types. Returns: result

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)

Inputs: end_date, durations, start_date, last_season, +4 more. Returns: result

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.

Inputs: no named parameters. Returns: result

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

Inputs: end_date, start_date. Returns: result

get_custom_item_by_idC

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

Args:
    item_id: The custom item ID

Inputs: item_id (required). Returns: result

get_custom_itemsB

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

Args:

Inputs: no named parameters. Returns: result

get_event_by_idC

Get detailed information for a specific event from Intervals.icu

Args:
    event_id: The Intervals.icu event ID

Inputs: event_id (required). Returns: result

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)

Inputs: end_date, start_date. Returns: result

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)

Inputs: refresh. Returns: result

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.

Inputs: sport. Returns: result

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

Inputs: days. Returns: result

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)

Inputs: end_date, start_date, include_all_fields. Returns: result

get_workoutA

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

Args:
    workout_id: The Intervals.icu workout ID.

Inputs: workout_id (required). Returns: result

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

Inputs: folder_id, sport_type. Returns: result

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

Inputs: query (required), limit. Returns: result

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)

Inputs: item_id (required), name, content, item_type, +2 more. Returns: result

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.

Inputs: settings_id (required), ftp, lthr, max_hr, +5 more. Returns: result

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.

Inputs: fat, hrv, date, mood, +16 more. Returns: result

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.

Inputs: entries (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.
      48
      40
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides MCP servers for Claude to access fitness data from Strava and intervals.icu, enabling natural language queries for activity analysis, advanced training metrics, and wellness tracking.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Intervals.icu that enables AI assistants to manage athletic training data, including activities, calendar events, wellness metrics, and workout libraries.
      19
      Apache 2.0