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.

Originally based on eddmann/intervals-icu-mcp (MIT licensed). This project is an independent continuation with significant bug fixes and new features — see Changelog for details.

Overview

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

• Activities (12 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 (10 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:

• 2 MCP Resources - Athlete profile with fitness metrics, and structured workout syntax reference for LLM-guided workout generation
• 7 MCP Prompts - Templates for common queries (training analysis, performance analysis, activity deep dive, recovery check, training plan review, weekly planning, workout generation)

Quick Start

Running with Claude Desktop, in 30 seconds:

1. Get your API key and athlete ID
2. Add this to your Claude Desktop config:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

3. Restart Claude and ask "Show me my activities from the last 7 days."

Prefer Claude Code or Cursor? See Client Configuration. Want to run from source or with Docker? See Installation & Setup.

Prerequisites

Install uv — it handles Python, dependencies, and execution in one tool:

# macOS / Linux
brew install uv
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

That's all you need — uvx will fetch Python and the package automatically. Docker is also supported as an alternative.

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 provided via environment variables (or .env file when running from source)
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 uvx (Recommended)

No clone, no manual install. Credentials are passed via the env block in your MCP client config (see Client Configuration).

# Optional: test it runs locally
INTERVALS_ICU_API_KEY=your_key INTERVALS_ICU_ATHLETE_ID=i123456 uvx intervals-icu-mcp

uvx downloads the package from PyPI on first run, caches it, and reuses the cache thereafter.

Option 2: From Source

For development or if you want to modify the server:

git clone https://github.com/hhopke/intervals-icu-mcp.git
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 3: 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).

Client Configuration

The server speaks MCP over stdio and works with any compliant client.

Claude Desktop

Add to your configuration file:

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

Using uvx (recommended)

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

From source

Requires having cloned the repo and run uv sync + uv run intervals-icu-mcp-auth.

{
  "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"
      ]
    }
  }
}

Claude Code

Register the server as a user-scoped MCP server:

claude mcp add intervals-icu --scope user \
  --env INTERVALS_ICU_API_KEY=your-key \
  --env INTERVALS_ICU_ATHLETE_ID=i123456 \
  -- uvx intervals-icu-mcp

Then in any Claude Code session, run /mcp to confirm intervals-icu is connected.

Cursor

Add to ~/.cursor/mcp.json (or the project-local .cursor/mcp.json):

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

Restart Cursor and open Settings → MCP to verify the server is listed.

Remote Deployment (HTTP / SSE)

By default the server runs over stdio — the right transport for local clients like Claude Desktop, Claude Code, and Cursor. For remote deployment (hosted MCP, reverse proxy, Docker-on-a-server), the server also supports HTTP-based transports via a --transport flag:

# Streamable HTTP (recommended for new remote clients)
intervals-icu-mcp --transport http --host 127.0.0.1 --port 8000

# Legacy SSE (for clients that haven't moved to streamable HTTP yet)
intervals-icu-mcp --transport sse --host 127.0.0.1 --port 8000

All flags:

⚠️ Security: do not expose an HTTP-mode server to untrusted networks.

The MCP protocol has no built-in authentication. Anyone who can reach the URL can exercise every tool with your credentials — read every activity, delete activities, modify your FTP, create calendar events, etc. Binding to 0.0.0.0 on a direct-exposed host (VPS, LAN with open port) is equivalent to publishing your Intervals.icu API key.

For remote access, prefer one of the following:

• Tailscale / Cloudflare Tunnel / ZeroTier — only your authenticated devices can reach the endpoint. Zero code changes, simplest option.
• Reverse proxy with auth (nginx + basic auth, Cloudflare Access, etc.) — terminates TLS and gates access.
• SSH tunnel — ssh -L 8000:localhost:8000 host if you just need occasional access from one machine.

Credentials are always read from INTERVALS_ICU_API_KEY and INTERVALS_ICU_ATHLETE_ID — use env vars (not a committed .env) when deploying to a shared host.

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.

Try the 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
• generate-workout - Generate a structured workout for any sport (cycling, running, swimming) with proper Intervals.icu syntax

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 sweet spot cycling workout for tomorrow"
"Create a tempo run with 800m repeats for Wednesday"
"Generate a CSS swim training session for Friday"
"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"

Structured Workouts: The server includes a complete workout syntax reference (intervals-icu://workout-syntax) that enables LLMs to generate valid structured workouts with proper power/HR/pace targets, zones, ramps, repeats, and cadence for cycling, running, and swimming.

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 (12 tools)

Activity Analysis (8 tools)

Athlete (2 tools)

Wellness (3 tools)

Events/Calendar (10 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):

Changelog

Bug fixes

• Power/HR/pace curves — rewrote curve models to match actual API response format, added required type parameter, fixed query parameter format
• Fitness summary — CTL/ATL/TSB now fetched from wellness endpoint (was returning empty from athlete endpoint)
• Duplicate events — fixed to correct API endpoint and batch body format
• Bulk delete events — fixed HTTP method and endpoint
• Activity intervals — API returns wrapped IntervalsDTO object, not a flat list; fixed model to extract icu_intervals
• Best efforts — added required stream parameter (watts, heartrate, pace); fixed response model to match API BestEfforts format
• Activity streams — API returns array of stream objects, not a dict; fixed endpoint to use .json extension and correct model
• Date parsing — event tools now handle ISO-8601 datetime formats correctly
• Missing event IDs — calendar and workout responses include event IDs, enabling update/delete operations

New features

• Structured Workout Generation — LLM-ready workout syntax resource (intervals-icu://workout-syntax) and generate_workout prompt for creating valid structured workouts across cycling, running, and swimming. Syntax spec attributed to MarvinNazari/intervals-icu-workout-parser (MIT)
• New Bulk/Streams APIs — full support for icu_apply_training_plan, icu_bulk_create_manual_activities and icu_update_activity_streams
• MCP Builder Standards — implemented universal icu_ naming prefix and destructiveHint safeguards for all modification tools
• Multi-athlete support — optional athlete_id parameter on activity, event, and calendar tools
• MCP verification prompts — verify-setup and verify-multi-athlete for live validation

Infrastructure

• Upgraded to FastMCP 3.x
• Added middleware integration tests
• Added tests for multi-athlete routing, model aliases, and date handling

Documentation

• Architecture overview — how the server, middleware, client, and tools fit together
• Testing guide — conventions for pytest + respx, fixtures, and running the suite
• Adding a new tool — step-by-step workflow for contributors

Contributing

Issues and pull requests are welcome. Before opening a PR, run make can-release locally to match what CI enforces (ruff, pyright, pytest). For new tools, follow the pattern in .claude/skills/add-tool/SKILL.md and add a respx-mocked test file alongside the implementation.

License

MIT License - see the LICENSE 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.