# intervals-mcp

An MCP server that lets Claude plan your cycling training in
[intervals.icu](https://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](https://docs.astral.sh/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`:

```json
{
  "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:

```json
{
  "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

```bash
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/`](docs/) go deeper than this README:

- [Writing workouts](docs/writing-workouts.md) — the syntax, the nesting trap,
  the length check, and how blocks work
- [Reading a review](docs/reading-a-review.md) — what compliance, MISSED, form
  and the hidden Strava activities actually mean
- [Tool reference](docs/tools.md) — every parameter and default
- [Troubleshooting](docs/troubleshooting.md) — 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](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](LICENSE).