intervals-icu

This MCP server provides access to your Intervals.icu data via a suite of 48 tools organized into nine categories, including Activities, Activity Analysis, Athlete metrics, Wellness, Events/Calendar, Performance/Curves, Workout Library, Gear Management, and Sport Settings. Additionally, it exposes a dedicated MCP Resource for the athlete profile and a set of prompts to help with common tasks like training analysis, performance evaluation, and weekly planning. To use it with Claude or other LLMs, configure Claude’s MCP integration to point at your server (for UV, point to the intervals-icu MCP entry as shown in the installation section). Once set up, you can ask natural-language questions such as: “Show my activity details from the last 7 days,” “Analyze my 20-minute power curve,” or “Update my FTP threshold to 275 watts,” and the server will route the request to the appropriate Intervals.icu API calls and return structured results suitable for further reasoning by the LLM. The included prompt templates help standardize typical queries (e.g., training analysis, performance analysis, recovery checks) and speed up delivery of actionable insights.

Prerequisites:

• Python 3.11+ and uv (or Docker)
• Access to your Intervals.icu API key and Athlete ID as described in the README

Option A: Using UV (recommended)

1. Clone or download the MCP repository and navigate to the project folder.
2. Install dependencies via UV (sync dependencies for your environment):

cd /path/to/intervals-icu-mcp
uv sync

3. Create credentials file (.env) or rely on interactive setup as described in the README. Example environment variables you’ll provide:

INTERVALS_ICU_API_KEY=your_api_key_here
INTERVALS_ICU_ATHLETE_ID=i123456

4. Start the MCP server with UV using the configuration example in the README (adjust the absolute path):

uv run --directory /ABSOLUTE/PATH/TO/intervals-icu-mcp intervals-icu-mcp

Option B: Using Docker

1. Build the image (from the README):

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

2. Create an environment file (intervals-icu-mcp.env) with your API key and athlete ID, as described:

INTERVALS_ICU_API_KEY=your_api_key_here
INTERVALS_ICU_ATHLETE_ID=i123456

3. Run the container with credentials mounted and the proper entrypoint if you wish to perform interactive setup or run the server directly:

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

4. To start the server in Docker without interactive setup, mount the .env and run the server entrypoint as appropriate for your deployment strategy (see README for exact command variations).

Prerequisites notes:

• Ensure network access to Intervals.icu APIs and that the API key has the necessary permissions.
• The athlete ID should be the one from your Intervals.icu profile URL in the format i123456.

Tips and common considerations:

• The environment file (.env) should contain INTERVALS_ICU_API_KEY and INTERVALS_ICU_ATHLETE_ID; these values are persisted for subsequent runs to avoid repeated prompts.
• If you encounter authentication issues, re-run the interactive setup (uv run intervals-icu-mcp-auth) to re-save credentials.
• For Claude integration, ensure the MCP server URL/endpoint is reachable by Claude (consider firewall rules or tunneling if needed).
• The MCP server exposes a resource for athlete profile and 6 prompt templates to streamline common tasks; reference these in your prompts to improve results.
• If you switch from UV to Docker (or vice versa), remember to update the mcp_config accordingly with the proper command and environment variables.
• Absolute paths should be used in UV configuration and Docker volume mounts to avoid path resolution issues.