Intervals.icu MCP

Minimal local stdio MCP server for Intervals.icu, generated from the official OpenAPI spec. Exposes every API operation as an MCP tool. Works with Claude Desktop, mcphost (Ollama / OpenRouter), Cline, and any other MCP client that speaks stdio; this repo is fully self-contained.

Files

|____spec/intervals-openapi-spec.json   # the Intervals.ICU API spec
|____README.md                          # that's me!
|____config.js.example                  # example config.js file
|____package.json                       # npm package dependency file
|____mcp-stdio.mjs                      # the MCP server
|____mcp-stdio.mjs                      # agent definition

Related MCP server: intervals-icu-mcp

Requirements

• Node.js ≥ 18

• An Intervals.icu API key — get it from https://intervals.icu/settings (bottom of the page, "Developer settings")

Install

Clone the repo and store it anywhere on your machine. Copy config.js.example to config.js and set INTERVALS_TOKEN to your Intervals.icu API key.

cp config.js.example config.js
npm install

Test it

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-stdio.mjs | python3 -mjson.tool | grep "name\"" | head

You should see on stderr:

[intervals-mcp] ready · 147 tools loaded
                "name": "updateLastSeenMessageId",
                "name": "updateMessage",
                "name": "deleteMessage",
                "name": "showWorkout",
                "name": "updateWorkout",
                "name": "deleteWorkout",
                "name": "getRecord",
                "name": "updateWellness",
                "name": "updateWellnessBulk",
                "name": "uploadWellness",

Press Ctrl-C to exit. The server is now ready to be driven by an MCP client.

Shrinking the tool surface (for small/local models)

The full spec generates 147 tools. Smaller models (qwen2.5:7b, llama3.1:8b, ...) struggle to pick the right one out of so many. Edit config.js to filter:

export const METHODS = ["GET"];                          // read-only server
export const TAGS    = ["Activity", "Wellness"];         // only these OpenAPI tags
export const INCLUDE = ["getActivities", "getWellness"]; // exact allow-list
export const EXCLUDE = ["someNoisyTool"];
export const DESCRIPTION_STYLE = "short";                // terse one-liners (vs "full")

Filters apply in order: METHODS → TAGS → INCLUDE → EXCLUDE. Restart the server after editing. Claude can handle all 147 tools comfortably; for Ollama/mcphost/Tome with small models, keep it under ~20 tools.

Claude Desktop

Edit Claude Desktop config file (create it if missing):

• MacOS - ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux - ~/.config/Claude/claude_desktop_config.json

• Windows - %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/local/mcp-stdio.mjs"],
      "env": { "INTERVALS_TOKEN": "your_api_key_here" }
    }
  }
}

The env block is optional if you already set INTERVALS_TOKEN in config.js. Restart Claude Desktop. The Intervals.icu tools are now available.

Agent - The AI Sports Scientist Layer - aka 'coach'

The 'coach'. Load the intervals-coach-agent.yaml defintion into your agents/custom modes definition. Once connected to this MCP server, your LLM gains real-time, programmatic visibility into your structured training data. It is pre-conditioned to act as an advanced exercise physiologist and endurance data companion—translating granular on-bike telemetry into accessible, motivational, and actionable insights.

Automated Ride & Stream Analysis

Every time the agent pulls a ride stream, it evaluates key metabolic and physiological markers:

• Biomechanical Metrics: Computes or extracts NP (Normalized Power), IF (Intensity Factor), TSS (Training Stress Score), and VI (Variability Index).

• Aerobic Efficiency: Monitors Pw:Hr (Aerobic Decoupling) to analyze cardiac drift and gauge metabolic penalty or heat stress during threshold efforts.

• Advanced Diagnostics: Identifies subtle performance trend signals, such as $VO_2\text{max}$ progressions, multi-day fatigue accumulation, or cadence decay over long durations.

Training Load Modeling (CTL / ATL / TSB)

The agent references systemic training loads using industry-standard formulas to help optimize your training progression without risking chronic burnout:

• Form Management: Automatically tracks TSB (Training Stress Balance) to keep your training stimulus safely inside the Optimal Training Zone (TSB between -10 and -30) and flags risk factors when entering the Danger Zone (TSB below -30).

• Progressive Overload Planning: Uses automated calculations to model micro-periodization blocks, suggesting safe week-over-week CTL Ramp Rates (+3 to +5 points max) and customized weekly TSS targets for build vs. recovery cycles.

Personalized Context & Asset Profiles

The agent maps your exact physiological baselines (FTP, CP, W', LTHR, HR Zones, and weight) and matches them contextually against your equipment profiles (e.g., Road vs. Gravel bike weights) and workout schemas. It gracefully handles structured step data, ensuring initial high-intensity intervals are never misclassified as warm-ups.

• You should edit intervals-coach-agent.yaml:customInstructions property with your own values. Some data might be available at intervals.icu already and the agent is capable of fetching it, but won't be any harm setting them up. Once configured, agent will be available thru /intervals-coach slug.

Note: This tool is built to enhance data literacy, illuminate physiological correlations, and simplify deep data exploration—it is designed to act as an analytical companion layer, not a replacement for a human cycling coach.

Extra Context with Strava MCP

Now that Strava has released their own MCP, you can bring additional context and data into this; altogether Strava and Intevals.icu data will provide a richier vision of your data.

Ollama / OpenRouter (via mcphost)

mcphost is a small CLI that bridges any MCP server to Ollama or OpenRouter models.

Model suggestion for Ollama:

• qwen3 or qwen2.5-coder:32b (if your machine can run it)

• llama3.1:8b — surprisingly solid at tool calls

• mistral-small3.1 / mistral-nemo — trained for function calling

Model suggestion for OpenRouter:

• anthropic/claude-3.5-sonnet, openai/gpt-4o-mini, google/gemini-2.0-flash

# install
go install github.com/mark3labs/mcphost@latest

# config: ~/.config/mcphost.intervals.json
{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/local/mcp-stdio.mjs"],
      "env": { "INTERVALS_TOKEN": "your_api_key_here" }
    }
  }
}

# run with Ollama
mcphost -m ollama:qwen2.5 --config ~/.config/mcphost.intervals.json

# or OpenRouter
mcphost -m openrouter:anthropic/claude-3.5-sonnet

If you'd rather a Desktop app instead of CLI, you can use Tome, which offers pretty straightforward configuration for adding MCP servers.

Authentication

Intervals.icu uses HTTP Basic auth. The server sends:

Authorization: Basic base64("API_KEY:${INTERVALS_TOKEN}")

This matches the official curl -u "API_KEY:TOKEN" style. If your token already contains a colon (e.g. myuser:mytoken), it is used verbatim.

Troubleshooting

• INTERVALS_TOKEN is not set — set it in config.js or export it as an environment variable.

• HTTP 401 — token is wrong or expired. Regenerate at https://intervals.icu/settings.

• Tool not found in Claude — restart Claude Desktop fully after editing the config file.