eddmann/intervals-icu-mcp

Intervals.icu MCP Server

A Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.

Overview

This MCP server provides 48 tools to interact with your Intervals.icu account, organized into 9 categories:

• Activities (10 tools) - Query, search, update, delete, and download activities
• Activity Analysis (8 tools) - Deep dive into streams, intervals, best efforts, and histograms
• Athlete (2 tools) - Access profile, fitness metrics, and training load
• Wellness (3 tools) - Track and update recovery, HRV, sleep, and health metrics
• Events/Calendar (9 tools) - Manage planned workouts, races, notes with bulk operations
• Performance/Curves (3 tools) - Analyze power, heart rate, and pace curves
• Workout Library (2 tools) - Browse and explore workout templates and plans
• Gear Management (6 tools) - Track equipment and maintenance reminders
• Sport Settings (5 tools) - Configure FTP, FTHR, pace thresholds, and zones

Additionally, the server provides:

• 1 MCP Resource - Athlete profile with fitness metrics for ongoing context
• 6 MCP Prompts - Templates for common queries (training analysis, performance analysis, activity deep dive, recovery check, training plan review, weekly planning)

Prerequisites

• Python 3.11+ and uv, OR
• Docker

Intervals.icu API Key Setup

Before installation, you need to obtain your Intervals.icu API key:

1. Go to https://intervals.icu/settings
2. Scroll to the Developer section
3. Click Create API Key
4. Copy the API key (you'll use it during setup)
5. Note your Athlete ID from your profile URL (format: i123456)

Installation & Setup

How Authentication Works

1. API Key - Simple API key authentication (no OAuth required)
2. Configuration - API key and athlete ID saved to .env file
3. Basic Auth - HTTP Basic Auth with username "API_KEY" and your key as password
4. Persistence - Subsequent runs reuse stored credentials

Option 1: Using UV

# Install dependencies
cd intervals-icu-mcp
uv sync

Then configure credentials using one of these methods:

Interactive Setup

uv run intervals-icu-mcp-auth

This will prompt for your API key and athlete ID and save credentials to .env.

Manual Setup

Create a .env file manually:

INTERVALS_ICU_API_KEY=your_api_key_here
INTERVALS_ICU_ATHLETE_ID=i123456

Option 2: Using Docker

# Build the image
docker build -t intervals-icu-mcp .

Then configure credentials using one of these methods:

Interactive Setup

# Create the env file first (Docker will create it as a directory if it doesn't exist)
touch intervals-icu-mcp.env

# Run the setup script
docker run -it --rm \
  -v "/ABSOLUTE/PATH/TO/intervals-icu-mcp.env:/app/.env" \
  --entrypoint= \
  intervals-icu-mcp:latest \
  python -m intervals_icu_mcp.scripts.setup_auth

This will prompt for credentials and save them to intervals-icu-mcp.env.

Manual Setup

Create an intervals-icu-mcp.env file manually in your current directory (see UV manual setup above for format).

Claude Desktop Configuration

Add to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using UV

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABSOLUTE/PATH/TO/intervals-icu-mcp",
        "intervals-icu-mcp"
      ]
    }
  }
}

Using Docker

{
  "mcpServers": {
    "intervals-icu": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/intervals-icu-mcp.env:/app/.env",
        "intervals-icu-mcp:latest"
      ]
    }
  }
}

Usage

Ask Claude to interact with your Intervals.icu data using natural language. The server provides tools, a resource, and prompt templates to help you get started.

Quick Start with MCP Prompts

Use built-in prompt templates for common queries (available via prompt suggestions in Claude):

• analyze-recent-training - Comprehensive training analysis over a specified period
• performance-analysis - Analyze power/HR/pace curves and zones
• activity-deep-dive - Deep dive into a specific activity with streams, intervals, and best efforts
• recovery-check - Recovery assessment with wellness trends and training load
• training-plan-review - Weekly training plan evaluation with workout library
• plan-training-week - AI-assisted weekly training plan creation based on current fitness

Activities

"Show me my activities from the last 30 days"
"Get details for my last long run"
"Find all my threshold workouts"
"Update the name of my last activity"
"Delete that duplicate activity"
"Download the FIT file for my race"

Activity Analysis

"Show me the power data from yesterday's ride"
"What were my best efforts in my last race?"
"Find similar interval workouts to my last session"
"Show me the intervals from my workout on Tuesday"
"Get the power histogram for my last ride"
"Show me the heart rate distribution for that workout"

Athlete Profile & Fitness

"Show my current fitness metrics and training load"
"Am I overtraining? Check my CTL, ATL, and TSB"

Note: The athlete profile resource (intervals-icu://athlete/profile) automatically provides ongoing context.

Wellness & Recovery

"How's my recovery this week? Show HRV and sleep trends"
"What was my wellness data for yesterday?"
"Update my wellness data for today - I slept 8 hours and feel great"

Calendar & Planning

"What workouts do I have planned this week?"
"Create a threshold workout for tomorrow"
"Update my workout on Friday"
"Delete the workout on Saturday"
"Duplicate this week's plan for next week"
"Create 5 workouts for my build phase"

Performance Analysis

"What's my 20-minute power and FTP?"
"Show me my heart rate zones"
"Analyze my running pace curve"

Workout Library

"Show me my workout library"
"What workouts are in my threshold folder?"

Gear Management

"Show me my gear list"
"Add my new running shoes to gear tracking"
"Create a reminder to replace my bike chain at 3000km"
"Update the mileage on my road bike"

Sport Settings

"Update my FTP to 275 watts"
"Show my current zone settings for cycling"
"Set my running threshold pace to 4:30 per kilometer"
"Apply my new threshold settings to historical activities"

Available Tools

Activities (10 tools)

Activity Analysis (8 tools)

Athlete (2 tools)

Wellness (3 tools)

Events/Calendar (9 tools)

Performance/Curves (3 tools)

Workout Library (2 tools)

Gear Management (6 tools)

Sport Settings (5 tools)

MCP Resources

Resources provide ongoing context to the LLM without requiring explicit tool calls:

MCP Prompts

Prompt templates for common queries (accessible via prompt suggestions in Claude):

License

MIT License - see file for details

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Intervals.icu. All product names, logos, and brands are property of their respective owners.