intervals-icu-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

MCP (Model Context Protocol) server for Intervals.icu — provides up to 69 tools, 4 resources, and 9 prompts for accessing training data, wellness metrics, and performance analysis through Claude and other LLMs. The default INTERVALS_ICU_DELETE_MODE=safe registers 66 tools; full registers all 69, none registers 61.

• Language: Python 3.11+
• Framework: FastMCP
• API Client: httpx (async)
• Validation: Pydantic v2
• Auth: pydantic-settings + .env

Development Commands

make install          # Install dependencies
make auth             # Set up Intervals.icu credentials (.env)
make run              # Run the MCP server
make test             # Run tests
make test/athlete     # Run tests matching "athlete"
make test/verbose     # Verbose test output
make lint             # Lint (ruff + pyright)
make format           # Auto-format code
make can-release      # Full pre-release check (same as CI)
make docker/build     # Build Docker image
make docker/run       # Run Docker container

Architecture (Quick Reference)

Component	File	Role
Server	server.py	Entry point, registers tools/resources/prompts
Middleware	middleware.py	Validates config, injects ICUConfig into context
Client	client.py	Async HTTP client (Basic Auth, 30s timeout)
Auth	auth.py	Loads credentials from .env
Response	response_builder.py	Consistent JSON structure (data/analysis/metadata)
Models	models.py	Pydantic models for API responses
Workout syntax	workout_syntax.py	Intervals.icu workout DSL reference for LLMs
Tools	tools/	13 tool modules (see below)

For detailed architecture: see docs/architecture.md

Tool Categories

1. activities.py — Query/manage activities
2. activity_analysis.py — Streams, intervals, best efforts
3. activity_messages.py — Notes/comments on activities
4. athlete.py — Profile, athlete notes, fitness metrics (CTL/ATL/TSB)
5. wellness.py — HRV, sleep, recovery
6. events.py — Calendar queries
7. event_management.py — Create/update/delete events
8. performance.py — Power/HR/pace curves
9. curves.py — HR and pace curve analysis
10. workout_library.py — Browse, create, and delete folders and plans; create/update/delete library workouts
11. gear.py — Manage gear and reminders
12. sport_settings.py — FTP, FTHR, pace thresholds
13. custom_items.py — Charts, custom fields, zones, etc.