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

---

📡 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

File	Purpose
README.md (this file)	Feature overview, installation, and usage examples
QUICKSTART.md	Fast setup guide with troubleshooting tips
API_REFERENCE.md	Complete endpoint specifications and parameters
CHANGELOG.md	Version history and release notes
EXTENSION_SUMMARY.md	Technical architecture and implementation details
PROJECT_SUMMARY.md	Project metrics, deliverables, and completion status

---

🖼️ 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

Feature	Desktop App (v1.0)	MCP Server (v2.1)
Total API Tools	36	36
Installation	✅ One-click	⚠️ Manual config
Claude Integration	✅ Built-in	✅ Claude Desktop
Credential Storage	✅ Secure (OS)	⚠️ .env file
Conversational UI	✅ Yes	❌ No
Settings Management	✅ In-app	❌ Manual
Update Checking	✅ Automatic	❌ Manual
Help & Guidance	✅ Yes	❌ No
Uptime Monitoring	✅ 99.5% SLO	❌ No
API Coverage	~95%	~95%
Supported Endpoints	All 36 tools	All 36 tools

---

✨ 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

Metric	Value
Total API Tools	36
API Coverage	~95% of public intervals.icu APIs
CRUD Support	Full (Create, Read, Update, Delete)
Code Lines	1,106
Documentation	7 comprehensive guides
Supported Operations	GET, POST, PUT, DELETE

---

🚀 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