intervals.icu Desktop + MCP Server

🏃 Your AI coaching assistant for intervals.icu training data

A standalone desktop application + Model Context Protocol (MCP) server that gives you complete access to intervals.icu training data through Claude AI. Manage every aspect of your training through natural conversation — from logging wellness data to organizing workout libraries to analyzing fitness trends.

�️ Standalone Desktop Application

A self-contained, production-ready desktop application for macOS and Windows. No manual Claude Desktop configuration needed. Just install, authenticate, and start asking Claude about your training data.

📥 Downloads (v1.0.0)

✅ macOS (Ready to download):

• 📦 IntervalsICU-1.0.0.dmg (33 MB) — Ready for installation

• 📋 Build Details — Build information and requirements

🚀 Seamless One-Click Installation

The DMG includes an automated install.sh script that handles everything automatically:

# 1. Mount the DMG (or double-click in Finder)
hdiutil attach IntervalsICU-1.0.0.dmg

# 2. Run the install script from the mounted volume
/Volumes/IntervalsICU/install.sh
# Or simply double-click install.sh in Finder

The script automatically:

• ✅ Detects and validates the app bundle

• ✅ Copies to /Applications folder

• ✅ Removes Gatekeeper quarantine attribute (eliminates "can't scan for malware" warnings)

• ✅ Verifies installation completeness

• ✅ Provides helpful error messages if issues occur

Installation options:

# Standard installation to /Applications
./install.sh

# Custom destination folder
./install.sh --dest ~/Desktop/Apps

# Force replacement if app already exists
./install.sh --force

# Verbose output for troubleshooting
./install.sh --verbose

# Show help
./install.sh --help

⚙️ Manual Installation (Alternative)

If you prefer to install manually:

1. Mount the DMG file (double-click)

2. Drag IntervalsICU.app to your Applications folder

3. Resolve Gatekeeper warnings (see troubleshooting below)

Troubleshooting – "Can't be scanned for malware" Error:

If you see a macOS warning that the app "can't be opened because it can't be scanned for malware":

Option 1 — Quick Fix (Recommended):

# Remove the quarantine attribute (one-time command)
xattr -d com.apple.quarantine /Applications/IntervalsICU.app

Option 2 — Using the Fix Script (from DMG):

# From the mounted DMG, run the provided fix script
/Volumes/IntervalsICU/fix-gatekeeper.sh /Applications/IntervalsICU.app

Option 3 — Manual Trust:

1. Right-click IntervalsICU.app and select "Open"

2. Click "Open" in the security dialog (one-time prompt)

3. App will be added to trusted apps

Windows (Coming soon): NSIS installer in development

✨ Key Features

• 🔐 Secure credential storage via OS-native Keychain (macOS) / Credential Manager (Windows)

• 💬 Conversational interface with Claude for natural-language training queries

• ⚙️ In-app settings management with API key updates and log viewing

• 🔄 Automatic update checking for new releases

• 📊 Performance monitoring and latency tracking

• 🎯 Context-aware help system with error guidance

• 🔒 99.5% uptime SLO with process resilience

Getting Started

# 1. Install dependencies
pip install -r requirements.txt

# 2. Configure credentials (interactive on first launch)
# Or use environment variables:
export INTERVALS_API_KEY="your_key_here"
export INTERVALS_ATHLETE_ID="i230309"
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Launch the desktop app
python -m desktop_app.main

Build & Deploy

macOS — ✅ Build Complete

The macOS distribution includes a seamless one-click installation experience:

Distribution Artifacts:

• Distributable .dmg available: IntervalsICU-1.0.0.dmg

• Includes install.sh — Automated installation script (handles Gatekeeper quarantine removal)

• Includes fix-gatekeeper.sh — Manual Gatekeeper resolution tool

• Build branch: build/macos-dmg-v1.0.0

Build Toolchain:

• PyInstaller 6.11.0+ — Bundles Python app to .app format

• create-dmg 1.3.3 — Creates professional DMG distribution

• Code signing with ad-hoc signatures + xattr Gatekeeper bypass

To rebuild locally:

chmod +x packaging/macos/build.sh
./packaging/macos/build.sh --version 1.0.0
# Add --sign --notarize for production builds (requires Developer ID)

Build Output:

• dist/macos/IntervalsICU-1.0.0.dmg (~32 MB, 64.7% compression)

• Contains: IntervalsICU.app, install.sh, fix-gatekeeper.sh, Applications symlink

Installation Scripts:

• packaging/macos/install.sh — Main automated installer (520 lines, 16 functions)

• packaging/macos/fix-gatekeeper.sh — Standalone Gatekeeper resolver

• packaging/macos/README.md — Build documentation and workflow

Windows — In Development

• NSIS installer coming soon

• Build script: packaging/windows/build.ps1

Testing

# Fast unit + integration tests
pytest tests/unit tests/integration -v

# Full test matrix
pytest tests/ -v -m "not e2e"

# All tests including e2e
pytest tests/ -v

Related MCP server: intervals.mcp

📡 MCP Server for Claude Desktop

For users preferring Claude Desktop integration instead of the standalone app, the MCP server is also available:

# 1. Install and configure
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your intervals.icu and Anthropic credentials

# 2. Run the MCP server
python server.py

# 3. In Claude Desktop config, add to `mcpServers`:
# {
#   "intervals-icu": {
#     "command": "python",
#     "args": ["/path/to/server.py"],
#     "env": {
#       "INTERVALS_API_KEY": "your_key",
#       "INTERVALS_ATHLETE_ID": "i230309",
#       "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v2"
#     }
#   }
# }

📖 Documentation

🖼️ Pre-Download UI Preview

Feature 004 adds a desktop-first browser preview so users can try the core chat UX before downloading the DMG.

Run locally

# from repository root
python -m http.server 8000
# then open http://localhost:8000/preview/

What the preview includes

• Interactive chat demo with deterministic simulated responses

• Authentication walkthrough with API-key guidance links

• Settings/help feature tour

• Download CTAs for macOS and Windows

• Fallback banner when preview modules fail to initialize

Validation tests

pytest tests/unit/test_preview_templates.py \
  tests/unit/test_preview_no_live_llm.py \
  tests/unit/test_preview_accessibility.py -v

pytest tests/integration/test_preview_*.py -v
pytest tests/e2e/test_preview_*.py -v

This preview intentionally uses sample data only and never accepts real credentials.

🎉 What's New in v1.0.0

Standalone Desktop Application Release — ✅ Now Available

A complete rewrite bundling the MCP server with a Claude-powered conversational UI for macOS and Windows:

📦 Release Status:

• ✅ macOS (.dmg) — Available — Download v1.0.0

• ⏳ Windows (NSIS) — In progress

• ✅ Source code — Tagged v1.0.0

Features:

• ✅ Standalone Desktop App — No Claude Desktop configuration needed

• ✅ Secure Credential Storage — OS-native Keychain/Credential Manager integration

• ✅ Conversational AI Interface — Ask Claude natural-language questions about your training

• ✅ 36 API Tools — Complete intervals.icu API coverage (~95%)

• ✅ In-App Settings — Update credentials, manage logging, check for updates

• ✅ 99.5% SLO — Process resilience with uptime tracking

• ✅ SC-004 Compliance — Response quality evaluation (95% pass threshold)

• ✅ Comprehensive Testing — 40+ tests covering unit/integration/performance/evaluation

• ✅ Production Packaging — Code-signed releases for macOS; NSIS installers for Windows

• ✅ Help & Guidance — Context-aware tooltips, FAQ, error remediation

v2.1.0 MCP Server (Foundation)

The underlying MCP server that powers the desktop app and can be used with Claude Desktop:

• ✅ Full CRUD operations on all major entities

• ✅ Workout Library management (9 tools)

• ✅ Training Plans support (4 tools)

• ✅ Coaching features (2 tools)

• ✅ Bulk operations and CSV export

• ✅ Complete documentation suite

Comparison: Desktop App vs MCP-Only

✨ API Features

👤 Athlete Profile

• get_athlete_profile — Retrieve FTP, weight, training zones, and account settings

💪 Wellness & Recovery

• get_wellness_data — Daily wellness metrics for a date range

• get_wellness_single — Wellness data for a specific date

• update_wellness — Update a single wellness entry

• update_wellness_bulk — Batch-update multiple wellness entries

Metrics covered: sleep quality and duration, HRV, resting heart rate, weight, body composition, subjective scores (fatigue, soreness, stress, motivation), readiness, CTL/ATL/TSB.

🚴 Training Activities

• get_activities — Workouts for a date range with key metrics

• get_activities_csv — Export all activities to CSV

• get_activity_details — Granular data including power/HR streams and detected intervals

• update_activity — Modify name, description, or type

• delete_activity — Remove an activity

📊 Fitness Analytics

• get_fitness_trends — CTL (Fitness), ATL (Fatigue), TSB (Form), and ramp rate

• get_power_curve — Best power efforts across different durations

📅 Calendar & Event Management

• get_calendars — List all calendars

• get_events — Planned races, workouts, and notes

• get_event — Details for a specific event

• create_event — Add races, workouts, or notes

• update_event — Modify an existing event

• delete_event — Remove a calendar event

• get_planned_workouts — Filter for upcoming scheduled training sessions

📚 Workout Library

• get_folders / create_folder / update_folder / delete_folder

• get_workouts / get_workout / create_workout / update_workout / delete_workout

📈 Training Plans

• get_training_plans / create_training_plan / update_training_plan / delete_training_plan

👥 Coaching

• get_coached_athletes — Athletes you coach with current fitness metrics

• get_wellness_summary — Wellness overview for coached athletes

⚡ Quick Stats

🚀 Installation

💡 For a faster path, see QUICKSTART.md. It includes platform-specific notes and a comprehensive troubleshooting section.

Prerequisites

• Python 3.10 or higher

• Claude Desktop

• An active intervals.icu account with API access

1. Get Your API Credentials

1. Log in to intervals.icu

2. Navigate to Settings → Developer Settings (near the bottom)

3. Click Generate API Key

4. Note your athlete ID from the URL: intervals.icu/athlete/{ATHLETE_ID}
   ⚠️ The athlete ID must include the i prefix (e.g., i230309)

2. Install Python Dependencies

cd intervals-icu-mcp
pip install -r requirements.txt

Or install in development mode:

pip install -e .

3. Test the Server (Recommended)

export INTERVALS_API_KEY="your_api_key"
export INTERVALS_ATHLETE_ID="your_athlete_id"   # e.g., i230309
export INTERVALS_API_BASE_URL="https://intervals.icu/api/v1"
python test_server.py

4. Configure Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "intervals-icu": {
      "command": "/usr/local/bin/python3",
      "args": ["/absolute/path/to/intervals-icu-mcp/server.py"],
      "env": {
        "INTERVALS_API_KEY": "your_api_key_here",
        "INTERVALS_ATHLETE_ID": "your_athlete_id_here",
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1"
      }
    }
  }
}

Important: Use the full path to Python (e.g., /usr/local/bin/python3, not just python). On macOS, run which python3 to find the correct path.

5. Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

💬 Usage Examples

Wellness & Recovery

• "What's my HRV trend over the past 2 weeks?"

• "Update my wellness for today: weight 70 kg, HRV 65 ms, sleep quality 4"

• "Am I getting enough recovery based on my recent wellness data?"

Training Analysis

• "Summarize my training volume for the past 30 days"

• "What were my hardest workouts this week?"

• "Export all my activities to CSV"

Fitness Trends

• "What's my current fitness (CTL) and form (TSB)?"

• "Am I building fitness too quickly? Check my ramp rate"

• "When was I at peak fitness in the last 90 days?"

Calendar & Planning

• "What races do I have coming up?"

• "Create a workout event for tomorrow: 60 min Z2 ride"

• "Delete the workout planned for next Tuesday"

Workout Library

• "List all my workout folders"

• "Add a new workout: 4×8 min @ 110% FTP with 4 min rest"

• "Create a folder called 'VO2max Sessions'"

Coaching

• "List all the athletes I coach"

• "What's the fitness trend for athlete John Doe?"

🔧 Troubleshooting

Server not appearing in Claude Desktop

1. Verify the config file path is correct for your OS

2. Validate JSON syntax: python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Confirm the absolute path to server.py is correct

4. Check that all three environment variables are present

401 / 403 Authentication Errors

• Confirm you're using v2.0.1 of server.py (includes the authentication fix)

• Ensure INTERVALS_API_BASE_URL is set

• Verify the athlete ID includes the i prefix

• Regenerate your API key in intervals.icu settings if needed

No Data Returned

• Use YYYY-MM-DD date format

• Try a broader date range

• Confirm you have data in intervals.icu for the requested period

For a full troubleshooting guide, see QUICKSTART.md.

🔒 Privacy & Security

• API credentials are stored locally in the Claude Desktop config file

• All requests go directly from your machine to intervals.icu — no third parties

• Claude processes responses locally on your machine

• Proper HTTP Basic Auth encoding (base64) for API key transmission

• All user-supplied IDs and dates are validated before use to prevent injection

• Client-side rate limiting (10 req/sec) protects against accidental API abuse

• HTTP requests enforce timeouts (30s request, 10s connect) and connection pool limits

• Error messages are sanitized — internal paths and stack traces are never exposed to the client

• .gitignore prevents accidental commit of .env files and credential configs

Best practices:

• Never share your API key or config file

• Protect the config file with restrictive permissions: chmod 600 claude_desktop_config.json

• Regenerate your API key if you suspect compromise

🤝 Contributing

~95% of the public intervals.icu API is already covered. Potential areas for future contribution include FIT/GPX/TCX file uploads, workout file downloads (.zwo, .mrc, .erg), real-time activity streams, advanced analytics, and webhook integration.

When contributing:

• Match existing code style and naming conventions

• Add docstrings to all new tools

• Update relevant documentation (README, QUICKSTART, API_REFERENCE)

• Add test cases to test_server.py

📋 Version History

v2.1.0 - Security Hardening (March 2025)

• ✅ Fixed Basic Auth encoding and removed credential leakage in debug logs

• ✅ Added input validation (dates, IDs), rate limiting, HTTP timeouts

• ✅ Sanitized error responses; added .gitignore for secrets protection

v2.0.0 - Major Release (March 2025)

• ✅ Extended from 8 to 36 API tools (4.5x increase)

• ✅ Added full CRUD operations on all major entities

• ✅ Workout Library management (9 new tools)

• ✅ Training Plans support (4 new tools)

• ✅ Coaching features (2 new tools)

• ✅ Bulk operations and CSV export

• ✅ Comprehensive documentation (7 guides)

v1.0.0 - Initial Release (March 2025)

• ✅ Basic read-only access to 8 core APIs

See CHANGELOG.md for detailed version history.

📜 License

MIT License — free to use and modify for your own training analysis needs.

🙏 Credits

Built for the Model Context Protocol to integrate intervals.icu with Claude Desktop.

• intervals.icu — comprehensive training analytics platform

• Anthropic — Claude and the MCP framework

• The intervals.icu community — API feedback and feature requests

💬 Support

• 📖 Setup: QUICKSTART.md

• 📚 API Reference: API_REFERENCE.md

• 📋 Changelog: CHANGELOG.md

• 🐛 Bug Reports: GitHub Issues

Made with ❤️ for athletes training smarter, not just harder

⭐ Star this repo if it's useful for your training!

v2.1.0 | Changelog | Quick Start | API Reference