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: 4.60 / 5.00 (Tier A+)
• Behavioral Annotations (ToolAnnotations): 100% of tools specify readOnlyHint, destructiveHint, and idempotentHint metadata.
• 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 19 tools.

---

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 fastembed for 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:latest

---

Configuration

Set the following environment variables:

Variable	Description	Default
INTERVALS_API_KEY	Your Intervals.icu API key (Required)	-
INTERVALS_ATHLETE_ID	Athlete ID	0 (authenticated user)
INTERVALS_BASE_URL	Intervals.icu API base URL	https://intervals.icu/api/v1
TOOL_ROUTING	Enable fastembed semantic tool discovery	false
ENABLE_CONTEXTFORGE_GATEWAY	Enable IBM ContextForge SSE gateway on port 8000	false

Obtaining your API Key

1. Log into your account at Intervals.icu.
2. Go to Settings -> API Access.
3. 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",
        "-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 or podman-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/ -v

License

Apache-2.0 License