intervals-mcp

An MCP server that lets Claude plan your cycling training in intervals.icu — and read back how it actually went.

Workouts land in the intervals.icu calendar, from which Zwift and Garmin pick them up. Afterwards Claude can review the outcome: planned versus actual, per-interval detail, fitness trend, power curve. So the next block is built on what happened, not on what was hoped for.

There is no training program in the code. You say what you want to train, Claude writes the workouts, this server delivers them and checks that intervals.icu understood them the way you meant.

"Check my FTP and build a 4-week VO2max block starting January 12. Three quality sessions a week, the rest Z2."

…and a week later: "How did last week go?"

Install

You need uv and an intervals.icu API key.

Nothing to clone — uvx runs the server straight from this repository.

Getting your API key

1. If you do not have an intervals.icu account yet, create one — it is free — and connect Strava, Garmin, Zwift or whatever records your rides, so your training actually lands there.
2. Open https://intervals.icu/settings and scroll to the bottom, to the Developer Settings section.
3. Copy the API key. It is about 25 characters of lowercase letters and digits.

That is all — there is no app to register and no OAuth flow to complete. The same section regenerates the key if you ever need to revoke it, which immediately invalidates the old one.

You do not need INTERVALS_ICU_ATHLETE_ID. It defaults to 0, meaning the account the key belongs to. Set it only if you are working with another athlete's data, such as one you coach.

Registering the server

Claude Code — put this in .mcp.json in your project, or run claude mcp add:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/staffanbergvall/intervals-mcp",
               "intervals-mcp"],
      "env": { "INTERVALS_ICU_API_KEY": "your-key-here" }
    }
  }
}

Claude Desktop — the same block goes in claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux). Restart the app fully — on Windows that means File → Exit, not just closing the window.

Then ask Claude to run check_connection. If it reports your FTP, you are set.

If your machine blocks executables from user directories

Some managed Windows environments (AppLocker and friends) refuse to run .exe files installed under the user profile, so uvx fails with Failed to spawn: intervals-mcp — Access is denied. The package is fine; only the generated console script is blocked. Start the module directly instead:

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uv",
      "args": ["run", "--with", "git+https://github.com/staffanbergvall/intervals-mcp",
               "python", "-m", "intervals_mcp.server"],
      "env": { "INTERVALS_ICU_API_KEY": "your-key-here" }
    }
  }
}

Zwift

Uploaded workouts appear under Workouts → Custom → Intervals.icu. Restart Zwift if they do not show up right away. If Zwift runs somewhere the intervals.icu integration is unavailable, export_block writes the block as .zwo files instead.

Tools

Tool	What it does
check_connection	Fetches FTP, threshold HR, max HR and power zones from the account
upload_block	Puts a block of workouts in the calendar and verifies the interpretation
list_block	Shows which workouts the server has added during a period
delete_block	Removes a block
export_block	Downloads the block as .zwo/.erg/.fit files
review_period	Planned versus actual for a period: compliance, missed workouts, and every other activity
get_activity	One completed activity with its intervals — per-rep watts, HR, cadence
get_fitness	CTL/ATL per day with client-computed form (TSB)
get_power_curve	Best power per duration over a period, in watts and W/kg

The icu://workout-syntax resource carries the full syntax for workout descriptions; Claude reads it before writing any workout.

The read tools report numbers, never judgements. What the numbers mean for your next block is decided in the conversation — that is the model's job, not the server's.

Workouts are always written in English — block names, workout names and descriptions — whatever language you and Claude are speaking. They end up in the calendar, in Zwift and on the Garmin head unit, and they outlive the conversation that created them.

What makes it safe to let a model write to your calendar

It can only touch its own workouts. Every workout this server creates is stamped with an external_id of the form mcp:<block>:<number>. Workouts you added by hand, imported, or got from a coach carry no such stamp — they are invisible to list_block and cannot be deleted by delete_block.

Uploading is idempotent. Re-uploading the same block name updates the workouts instead of duplicating them, so you correct a block by simply running it again. If the corrected version has fewer workouts than before, the leftovers from the earlier version are reported rather than left silently in your calendar.

The length check. The dangerous failure is not an HTTP error — it is a workout that uploads without protest and is interpreted wrong. After every upload the server compares intervals.icu's own parse of each workout against the duration you stated, and says so when they diverge:

!!  2027-01-14  30/15 3x13
      3 steps, 36 min (stated: 63 min)
      WARNING: Line 6: '13x' directly follows '3x'. Nested repeats are not
      supported — the outer one swallows the inner. Write the sets out one by
      one instead.
      WARNING: Duration mismatch: you stated 63 min, the server parsed 36.0 min
      (43% off). Something in the description was not read the way you meant.

A workout the server returns no event for is reported the same way — as a warning, never as silence.

Nested repeats are not supported by intervals.icu. 3x around 13x gives 3 rounds, not 39, and intervals.icu does not complain. Verified against the live API — worth knowing even if you never use this server.

Your API key

The key grants full read and write access to your intervals.icu account, not just to workouts. Treat it like a password: keep it in your MCP client's config or environment, never in a file you commit. This server sends it only to intervals.icu, over HTTPS, and never logs it.

If you think a key has leaked, regenerate it at https://intervals.icu/settings — that invalidates the old one at once.

For local development you can put it in a .env file instead (see .env.example); .env is gitignored.

Development

git clone https://github.com/staffanbergvall/intervals-mcp
cd intervals-mcp
uv sync
uv run python -m pytest -q      # 138 tests, no network traffic

The tests cross the same interfaces production does: the pure logic directly, the API client through httpx.MockTransport, and the tool bodies with the real client behind a mock transport. Nothing touches a live calendar.

The repository ships a path-free .mcp.json, so Claude Code picks up your working copy when you open the project.

On the locked-down machines described above, the same restriction applies to .venv/Scripts/ — run tests as uv run python -m pytest, never as pytest.

Documentation

The pages in docs/ go deeper than this README:

• Writing workouts — the syntax, the nesting trap, the length check, and how blocks work
• Reading a review — what compliance, MISSED, form and the hidden Strava activities actually mean
• Tool reference — every parameter and default
• Troubleshooting — when something is not working

Status

A personal project, shared because it might be useful to someone else. Issues and pull requests are welcome, but this is a spare-time thing — there is no guarantee of a timely response. See CONTRIBUTING.md before opening a PR.

Not affiliated with or endorsed by intervals.icu, Zwift or Garmin. It talks to the public intervals.icu API with your own key.

MIT licensed.