intervals-icu-mcp

intervals-icu-mcp

MCP server that connects Claude to your training data on intervals.icu — advanced physiological analysis with AI

What it is and who it's for

intervals-icu-mcp exposes your intervals.icu data — activities, wellness, calendar, second-by-second streams — as tools callable by Claude Desktop, plus a layer of proprietary physiological analysis (CCI, HRV correction, field aerodynamics) built on top. It runs locally: Claude Desktop connects to the server via MCP (stdio), and the server talks to the intervals.icu API using your API key.

It's not just another dashboard. It enables analysis that doesn't exist today in any training platform: separating sympathetic fatigue from real aerobic improvement by cross-referencing HRV Z-Score with power and heart rate, detecting when a lower "cardiac cost" is actually cardiac suppression rather than efficiency, or estimating your CdA in the air from position angles without setting foot in a wind tunnel. All conversational, in natural language, with persistent memory across sessions.

Quick start

1. Clone the repo

   git clone https://github.com/andiarenaleandro-ux/intervals-icu-mcp.git
   cd intervals-icu-mcp
   

2. Install everything with one command

   python install.py
   

   Creates the virtual environment, installs dependencies, and copies the example config files (.env, SYSTEM_PROMPT.md, athlete_profile.json).

3. Edit .env with your intervals.icu credentials:

   • INTERVALS_ATHLETE_ID — visible in the URL: https://intervals.icu/athlete/i12345 → your ID is i12345
   • INTERVALS_API_KEY — generate it in intervals.icu → Settings → Developer Settings → API Key

4. Connect Claude Desktop automatically

   python setup_claude.py
   

   Detects your operating system, finds claude_desktop_config.json, and adds the server entry without touching the rest of your configuration (other MCPs stay intact). Shows you the JSON before writing and asks for confirmation.

5. Restart Claude Desktop. The tools icon should appear with the intervals-icu tools available.

Main features

• Full CRUD for intervals.icu — activities, wellness, calendar, sport settings.
• Second-by-second streams — power, heart rate, cadence, speed, elevation, for fine-grained analysis.
• Local .fit file analysis — no need for the activity to be uploaded to intervals.icu.
• CCI (Cardiac Cost Index) — proprietary cardiac efficiency metric (HR / %FTP) that separates real work from recovery laps.
• HRV Z-Score correction — distinguishes sympathetic fatigue from real adaptation when CCI drops.
• Freshness Ratio matrix (HRV × TSB) — 4 clinical quadrants (fresh, optimal load, acute overload, non-functional overreaching) instead of looking at TSB in isolation.
• Cardiac suppression detection — identifies when a lower heart rate is autonomic nervous system exhaustion, not improved efficiency.
• Aerodynamics — estimated CdA from position and real field CdA (Martin et al. 1998 method).
• Persistent biomechanical profile — fitting history, position angles, injuries, training context.
• Local SQLite memory — weekly and per-session snapshots for longitudinal trends without re-spending tokens on refetches.

Available tools (48)

Activities (7)

Fitness & zones (4)

Wellness (3)

Athlete profile (3)

Calendar (7)

.fit files (3)

Extended profile (5)

Aerodynamics (4)

Advanced analytics (3)

Memory & trends (9)

Project structure

intervals-icu-mcp/
├── install.py                     ← Installer: venv + dependencies + config
├── setup_claude.py                ← Configures Claude Desktop automatically
├── requirements.txt
├── .env.example                   ← Credentials template
├── SYSTEM_PROMPT.example.md       ← Agent role/persona template
├── athlete_profile.example.json   ← Biomechanical profile template
├── fit_files/                     ← Your local .fit files
├── db/                            ← SQLite (created automatically)
└── server/
    ├── main.py                    ← Entry point: registers all tools
    ├── config.py                  ← Configuration (reads .env)
    └── tools/
        ├── activities.py
        ├── fitness.py
        ├── wellness.py
        ├── athlete.py
        ├── calendar.py
        ├── fit_parser.py
        ├── profile.py
        ├── aerodynamics.py
        ├── analytics.py
        └── memory.py

Customization

SYSTEM_PROMPT.md

This file defines how Claude behaves as your sports analyst. Copy the example and replace the placeholders with your data.

cp SYSTEM_PROMPT.example.md SYSTEM_PROMPT.md   # install.py does this automatically

If you don't know your FTP or LTHR, intervals.icu estimates them automatically from your training data. Check Sport Settings after a few weeks of recorded activities.

The interpretation rules (CCI, HRV correction, drift thresholds) are universal and don't need modification — they work for any athlete.

athlete_profile.json

This file stores data that intervals.icu doesn't have: bike fitting, position angles, injury history, and training context. It's optional — the MCP works without it, but the aerodynamics and biomechanics tools need it for full analysis.

cp athlete_profile.example.json athlete_profile.json   # install.py does this automatically

The most important fields to fill in:

• equipment.bike.model — your bike
• equipment.bike.power_meter — your power meter
• bike_fit.crank_length_mm.current — your current crank length in mm
• bike_fit.position_current — your position angles (if you have them from a fit)
• physiology.ftp_w — same as {FTP} above

Position angles (torso, hip, knee, elbow) are measured during a professional bike fit. If you haven't had one, leave them null — the aerodynamics tools will use literature reference values instead.

You can update this file anytime through Claude by saying "update my crank length to 165mm" — the agent writes to the file directly.

Session naming convention

The analytics engine groups sessions by name to compare equivalent workouts week over week. Name your activities in intervals.icu using these standard prefixes for automatic detection:

This is optional. You can also compare sessions manually by providing activity IDs — the naming convention just enables automatic grouping.

The power threshold that separates a real work lap from warmup/recovery for each of these prefixes is SESSION_POWER_THRESHOLD in server/tools/analytics.py. Adjust it if the way you structure sessions differs from the standard convention.

Example queries

"Show me my activities from the last week"
"Analyze my last FTP session — I want the CCI and the drift"
"Compare my last 4 BIKE_FTP sessions and tell me if I'm improving"
"Estimate my CdA with my current position"
"How's my CTL looking ahead of my next race?"

Technology

• Stack: Python 3.10+, FastMCP, httpx, fitparse, SQLite
• Protocol: MCP (Model Context Protocol)
• Transport: stdio (local) — each user runs their own server, no shared backend

Limitations

• Requires Claude Desktop (or any MCP client compatible with stdio).
• One user = one athlete (single-tenant); not designed for multiple athletes on the same instance.
• No automated tests or CI.
• No remote deployment — runs locally, no hosted version.

Contributing

Want to add a tool, fix a bug, or improve the analysis? Check out CONTRIBUTING.md for the workflow and project conventions.

License

MIT