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, ChatGPT, 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.md for details.

Overview

70 tools spanning activities, activity analysis, activity messages, athlete profile, wellness, events/calendar, performance curves, workout library, gear, sport settings, and custom items — plus 4 MCP Resources (athlete profile, workout syntax, event categories, custom item schemas) and 9 MCP Prompts (training analysis, recovery check, weekly planning, and more). See Available Tools for the per-category breakdown.

Quick Start

Or for 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, Cursor, or ChatGPT? 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. brew install uv on macOS/Linux, or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" on Windows. From there, uvx fetches Python and the package automatically. Docker is also supported as an alternative.

Intervals.icu API Key Setup

Before installation, obtain your Intervals.icu API key:

1. Go to https://intervals.icu/settings → Developer → Create API Key.
2. Copy the key, and note your Athlete ID from your profile URL (format: i123456).

Installation & Setup

Nothing to install separately if you use the recommended setup. uvx (which ships with uv) automatically downloads and caches the intervals-icu-mcp package the first time your MCP client launches it — just paste the config snippet from Client Configuration into your client and you're done.

Alternative: from source — for development or local modifications

git clone https://github.com/hhopke/intervals-icu-mcp.git
cd intervals-icu-mcp
uv sync
uv run intervals-icu-mcp-auth  # interactive credential setup; or create .env manually:
#   INTERVALS_ICU_API_KEY=your_api_key_here
#   INTERVALS_ICU_ATHLETE_ID=i123456

Then point your MCP client at this checkout — see the From source snippet inside each client below.

Alternative: Docker

docker build -t intervals-icu-mcp .

# Interactive credential setup (creates intervals-icu-mcp.env in the current directory):
touch intervals-icu-mcp.env  # pre-create the file so Docker mounts it as a file, not a dir
docker run -it --rm \
  -v "$(pwd)/intervals-icu-mcp.env:/app/.env" \
  --entrypoint= intervals-icu-mcp:latest \
  python -m intervals_icu_mcp.scripts.setup_auth