A
licenseA
qualityD
maintenanceA Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.
48
39
MIT
intervals.icu-mcp
by jelmervdm
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 show my last 5 rides"
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
Model Context Protocol (MCP) server for Intervals.icu, providing athletic training analysis, activity management, calendar event planning, wellness tracking, and workout library integration to AI assistants like Claude Desktop, Cursor, and IBM ContextForge.
🏆 Tool Definition Quality Score (TDQS)
This server is audited against the Tool Definition Quality Score (TDQS) framework to guarantee optimal function calling, type safety, and runtime safety for LLMs:
Score:
5.00 / 5.00(Tier A+)Behavioral Annotations (
ToolAnnotations): 100% of tools specifyreadOnlyHint,destructiveHint, andidempotentHintmetadata.Parameter Descriptions: 100% of tool parameters use explicit Pydantic
Annotated[T, Field(description=...)]metadata.Operational Guidelines: Standardized docstrings detailing explicit "Use when..." context across all 17 tools.
---------------- SCORECARD METRICS ----------------
Tools Evaluated : 17
Behavioral Annotations : 17 / 17 (100.0%)
100% Parameter Descriptions : 17 / 17 (100.0%)
Usage Guidelines (Docstrings): 17 / 17 (100.0%)
Overall TDQS Score : 5.00 / 5.00
TDQS Quality Tier : Tier A+
========================================================Related MCP server: intervals-icu-mcp
Features
Athlete Profile: Fetch FTP, LTHR, max HR, weight, and training zone settings.
Activities: Search, view detailed metrics, update activity names/types, delete activities, and comment on activities.
Calendar & Events: Manage planned workouts, races, and note events on your training calendar.
Wellness Tracking: Log and retrieve daily wellness metrics (HRV, resting HR, weight, sleep, readiness, fatigue, mood).
Workout Library: Browse workout folders and structured training library workouts.
Semantic Tool Routing: Optional embedding-based tool discovery using
fastembedfor minimal context overhead.ContextForge Gateway Support: Built-in support for IBM ContextForge Gateway SSE transport.
Installation
Local Editable Install
Clone the repository and install in editable mode:
git clone https://github.com/jelmervdm/intervals.icu-mcp.git
cd intervals.icu-mcp
pip install -e ".[dev,router]"Container Deployment (Podman / Docker)
Pull pre-built image or build locally:
podman pull ghcr.io/jelmervdm/intervals.icu-mcp:latestConfiguration
Set the following environment variables:
Variable | Description | Default |
| Your Intervals.icu API key (Required) | - |
| Athlete ID |
|
| Intervals.icu API base URL |
|
| Enable fastembed semantic tool discovery |
|
| Enable IBM ContextForge SSE gateway on port 8000 |
|
Obtaining your API Key
Log into your account at Intervals.icu.
Go to Settings -> API Access.
Copy your API Key.
Usage with VS Code, Antigravity IDE & Claude Desktop
Add to your .vscode/mcp.json or MCP configuration file ("servers" for VS Code / Antigravity IDE, or "mcpServers" for Claude Desktop):
Option 1: Docker / Podman
Podman is fully supported on Fedora/RHEL as a rootless drop-in replacement for Docker:
{
"servers": {
"intervals": {
"command": "podman",
"args": [
"run", "-i", "--rm", "--pull=newer",
"-e", "INTERVALS_API_KEY",
"-e", "INTERVALS_ATHLETE_ID",
"ghcr.io/jelmervdm/intervals.icu-mcp:latest"
],
"env": {
"INTERVALS_API_KEY": "your_api_key_here",
"INTERVALS_ATHLETE_ID": "0"
}
}
}
}Tip for Docker vs Podman: Replace
"command": "podman"with"command": "docker"if using standard Docker orpodman-docker. Always use-i(interactive stdin) and never-t(TTY) to avoid formatting corruption over stdio.
Option 2: Local Python Execution (without PyPI)
Via uv (local workspace directory):
{
"servers": {
"intervals": {
"command": "uv",
"args": ["--directory", "/path/to/intervals.icu-mcp", "run", "intervals-icu-mcp-server"],
"env": {
"INTERVALS_API_KEY": "your_api_key_here",
"INTERVALS_ATHLETE_ID": "0"
}
}
}
}Via python (editable install pip install -e .):
{
"mcpServers": {
"intervals": {
"command": "python",
"args": ["-m", "intervals_mcp.server"],
"env": {
"INTERVALS_API_KEY": "your_api_key_here",
"INTERVALS_ATHLETE_ID": "0"
}
}
}
}Via uvx directly from GitHub repository:
{
"mcpServers": {
"intervals": {
"command": "uvx",
"args": ["--from", "git+https://github.com/jelmervdm/intervals.icu-mcp.git", "intervals-icu-mcp-server"],
"env": {
"INTERVALS_API_KEY": "your_api_key_here",
"INTERVALS_ATHLETE_ID": "0"
}
}
}
}Available Tools
Athlete Tools
get_athlete_profile(athlete_id="0"): Retrieve athlete profile, FTP, zones, and settings.
Activity Tools
list_activities(oldest, newest, athlete_id="0"): List activities in a date range (YYYY-MM-DD).get_activity(activity_id): Retrieve detailed metrics for a specific activity.update_activity(activity_id, name, description, type, gear): Update activity details.delete_activity(activity_id): Delete an activity.list_activity_messages(activity_id): Retrieve activity comments/messages.add_activity_message(activity_id, text): Post a comment/note to an activity.
Calendar & Event Tools
list_events(oldest, newest, athlete_id="0"): List calendar events and planned workouts.get_event(event_id, athlete_id="0"): Fetch details of a planned workout or event.create_event(start_date_local, name, description, type, category, athlete_id="0"): Plan a workout or event.update_event(event_id, start_date_local, name, description, athlete_id="0"): Update a planned event.delete_event(event_id, athlete_id="0"): Delete a calendar event.
Wellness Tools
list_wellness(oldest, newest, athlete_id="0"): List daily wellness entries.get_wellness(date, athlete_id="0"): Fetch wellness record for a date (YYYY-MM-DD).update_wellness(date, weight, resting_hr, hrv, sleep_secs, readiness, fatigue, mood, comments, athlete_id="0"): Update wellness metrics.
Workout Library Tools
list_workout_folders(athlete_id="0"): List folders in the workout library.list_workouts(folder_id, athlete_id="0"): List structured library workouts.
AI Coaching Skills
For AI agents acting as endurance coaches, this MCP server pairs directly with the Athletic Performance Coaching Skills repository.
While intervals.icu-mcp provides data access (activity streams, daily wellness, calendar planning, and workout library management), jelmervdm/skills provides physiological rules, workout analysis workflows, and evidence-based training prescription guardrails for AI assistants.
Available Skills in jelmervdm/skills
Cycling: Coggan power/HR zones, aerobic decoupling ($P\text{:}HR$), interval compliance scoring, periodization, and race pacing.
Running: Jack Daniels VDOT pacing formulas, cadence dynamics, Grade-Adjusted Pace (GAP), rTSS, and race strategies.
Swimming: Critical Swim Speed (CSS), SWOLF stroke efficiency, send-off clocks, and open-water drafting.
Triathlon: Multi-sport stress balancing ($\text{TSS} + \text{rTSS} + \text{sTSS}$), brick workout design, and T1/T2 transition execution.
Ironman: Long-course 70.3/140.6 pacing budgets, high-carb gut training ($80\text{--}120\text{g/hr}$), special needs strategy, and 21-day tapers.
Cross-Country Skiing: Skate & Classic subtechnique kinematics (V1/V2, Diagonal, Double Poling), dryland roller skiing, and marathon ski pacing.
Weight Training: RIR/RPE autoregulation, strength/hypertrophy mesocycles, and concurrent endurance training integration.
Development
git clone https://github.com/jelmervdm/intervals.icu-mcp.git
cd intervals.icu-mcp
pip install -e ".[dev,router]"
pytest tests/ -vLicense
Available Tools
19 toolsadd_activity_messageA
Post a comment/note to an activity conversation thread.
Use to add athlete/coach feedback to a workout. To edit activity description directly, use update_activity instead.
Args: activity_id: Activity ID. text: Comment or message text to attach.
Inputs: text (required), activity_id (required). Returns: result
call_routed_toolA
Invoke a tool returned by route_tools.
Args: name: Exact tool name from route_tools output. arguments: JSON object of arguments.
Inputs: name (required), arguments. Returns: result
create_eventA
Create a new planned workout, race event, or note on the calendar.
Use when scheduling upcoming training or race events. To modify an existing calendar event, use update_event.
Args: start_date_local: Local start time in YYYY-MM-DDTHH:MM:SS format (e.g. "2026-07-27T08:00:00"). name: Title of event/workout. description: Workout steps or description text. type: Activity type (e.g. "Ride", "Run", "Swim"). category: Event category (e.g. "WORKOUT", "RACE", "NOTE"). athlete_id: Athlete ID (defaults to "0").
Inputs: name (required), start_date_local (required), type, category, +2 more. Returns: result
delete_activityADestructiveIdempotent
Delete an activity by ID from Intervals.icu calendar.
Use to permanently remove duplicate or invalid uploaded activity files.
Args: activity_id: Unique activity ID to delete.
Inputs: activity_id (required). Returns: result
delete_eventADestructiveIdempotent
Delete a calendar event or planned workout by ID.
Use to remove canceled workouts or events from the training calendar.
Args: event_id: ID of the event to delete. athlete_id: Athlete ID (defaults to "0").
Inputs: event_id (required), athlete_id. Returns: result
get_activityARead-only
Get full details and detailed metrics for a single activity.
Use when analyzing specific workout metrics (e.g. Normalized Power, TSS, HR zones). To list multiple activities across dates, use list_activities.
Args: activity_id: The unique ID of the activity.
Inputs: activity_id (required). Returns: result
get_athlete_profileARead-only
Fetch athlete profile details, including FTP, LTHR, weight, max HR, and training zones.
Use to inspect baseline athletic physiological metrics and training zone configurations.
Args: athlete_id: Athlete ID (defaults to "0" for the authenticated athlete).
Inputs: athlete_id. Returns: result
get_eventARead-only
Fetch details of a single calendar event or planned workout.
Use when inspecting target workout steps or race plans for a specific calendar item. To list events across a date range, use list_events.
Args: event_id: Calendar event ID. athlete_id: Athlete ID (defaults to "0").
Inputs: event_id (required), athlete_id. Returns: result
get_wellnessARead-only
Fetch wellness record for a specific date.
Use when examining a single day's physiological metrics. To list metrics across multiple days, use list_wellness.
Args: date: Date string in YYYY-MM-DD format. athlete_id: Athlete ID (defaults to "0").
Inputs: date (required), athlete_id. Returns: result
list_activitiesARead-only
List completed workout activities within a date range.
Use when retrieving activity summaries across a date range. To fetch detailed power/HR streams or intervals for a single activity, use get_activity.
Args: oldest: Start date in YYYY-MM-DD format (e.g. "2026-07-01"). newest: End date in YYYY-MM-DD format (e.g. "2026-07-26"). athlete_id: Athlete ID (defaults to "0" for authenticated athlete).
Inputs: newest (required), oldest (required), athlete_id. Returns: result
list_activity_messagesARead-only
Retrieve comments and coach messages associated with an activity.
Use to view discussion thread on an activity. To post a new message, use add_activity_message.
Args: activity_id: Activity ID.
Inputs: activity_id (required). Returns: result
list_eventsARead-only
List calendar events and planned workouts between dates.
Use when browsing planned workouts, notes, or race events on the calendar. To fetch details of a specific planned event, use get_event.
Args: oldest: Start date (YYYY-MM-DD). newest: End date (YYYY-MM-DD). athlete_id: Athlete ID (defaults to "0").
Inputs: newest (required), oldest (required), athlete_id. Returns: result
list_wellnessARead-only
List daily wellness records in a date range.
Use when tracking trends in sleep, HRV, weight, and readiness over time. To inspect a single day's wellness record, use get_wellness.
Args: oldest: Start date (YYYY-MM-DD). newest: End date (YYYY-MM-DD). athlete_id: Athlete ID (defaults to "0").
Inputs: newest (required), oldest (required), athlete_id. Returns: result
list_workout_foldersARead-only
List workout folders in the athlete library.
Use when browsing workout library structure. To list workouts within a folder, use list_workouts.
Args: athlete_id: Athlete ID (defaults to "0").
Inputs: athlete_id. Returns: result
list_workoutsARead-only
List structured library workouts.
Use when browsing reusable workout templates. To schedule a workout onto the calendar, use create_event.
Args: folder_id: Optional workout folder ID to filter by. athlete_id: Athlete ID (defaults to "0").
Inputs: folder_id, athlete_id. Returns: result
route_toolsA
Find tools relevant to your task. Call this FIRST, then use call_routed_tool to invoke them.
Args: query: Natural-language description of what you want to do (e.g. "get athlete FTP").
Inputs: query (required). Returns: result
update_activityAIdempotent
Update metadata fields on an activity. Only specified fields are updated.
Use when editing activity titles, descriptions, types, or gear assignment. To post a comment message, use add_activity_message instead.
Args: activity_id: ID of the activity to update. name: New name for the activity. description: Updated description or notes. type: Activity type (e.g., "Ride", "Run", "Swim", "WeightTraining"). gear: List of gear names or IDs used.
Inputs: activity_id (required), gear, name, type, +1 more. Returns: result
update_eventAIdempotent
Update an existing calendar event or planned workout.
Use when modifying workout targets, start dates, or titles. To schedule a new event, use create_event.
Args: event_id: Calendar event ID to update. start_date_local: Updated local start time (YYYY-MM-DDTHH:MM:SS). name: Updated name. description: Updated workout description or details. athlete_id: Athlete ID (defaults to "0").
Inputs: event_id (required), name, athlete_id, description, +1 more. Returns: result
update_wellnessAIdempotent
Update daily wellness metrics for a given date.
Use to log or update daily sleep, weight, HRV, and subjective readiness. Updates only specified fields.
Args: date: Date in YYYY-MM-DD format. weight: Body weight in kg. resting_hr: Resting heart rate in bpm. hrv: Heart rate variability. sleep_secs: Total sleep duration in seconds. readiness: Readiness score. fatigue: Subjective fatigue score. mood: Subjective mood score. comments: Optional daily notes/comments. athlete_id: Athlete ID (defaults to "0").
Inputs: date (required), hrv, mood, weight, +6 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A4.1/5.0
Scored across 19 tools
Disambiguation5/5
Each tool targets a distinct resource and action: activities vs events vs wellness vs workouts are clearly separated. The meta tools (route_tools/call_routed_tool) stand apart from the domain tools, and get/list/update/delete versions are unambiguous.
Naming Consistency5/5
All domain tools follow a consistent verb_noun pattern (list_activities, get_event, update_wellness) using snake_case. The two meta tools deviate slightly but are a separate routing layer, not part of the core domain pattern.
Tool Count4/5
19 tools is toward the upper end of reasonable for a comprehensive platform API covering athlete profile, activities, events, wellness, and workouts. The count is justified by the breadth of functionality, though it could feel heavy for simple tasks.
Completeness4/5
Full CRUD coverage for activities and events, plus read/update for wellness and read-only for workout library. The only notable gap is lack of create/update/delete for structured workouts, but scheduling is handled via events, so the surface is largely complete for the domain.
Maintenance
ActivityNo data
ResponsivenessOutdated data
Related MCP Connectors
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
Connect Intervals.icu to Claude and ChatGPT: read training, plan workouts. Training never stored.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
Strava MCP tools for AI: athletes, activities, segments, clubs, routes. Powered by HAPI MCP server.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server that connects AI agents to Intervals.icu, enabling access to training data such as activities, wellness metrics, calendar events, gear, power curves, and custom items. Includes a running coach AI template for automated post-session analysis.1923 npm1MIT
- 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
- AlicenseNot gradedqualityCmaintenanceAn MCP server that connects Claude to intervals.icu training data, enabling advanced physiological analysis, activity and wellness management, and conversational insights using proprietary metrics like CCI and HRV correction.MIT