# Intervals.icu MCP Server

An MCP (Model Context Protocol) server that integrates [Intervals.icu](https://intervals.icu) with AI assistants like Claude or ChatGPT. It exposes your training data, wellness records, planned workouts, and calendar events through a set of tools that Claude can call directly.

## Features

- **Athlete profile & settings** — retrieve profile info and sport-specific settings (FTP, LTHR, HR zones, pace zones)
- **Activities** — list, search, and get detailed metrics for completed workouts
- **Wellness** — read daily wellness records (weight, resting HR, HRV, sleep, soreness, fatigue, stress, mood)
- **Training calendar** — list, create, and update planned events (workouts, races, notes, and more)
- **Routes** — browse saved routes with optional GPS path data
- **Summary stats** — aggregate training load, distance, and time over a date range

## Available Tools

| Tool | Description |
|---|---|
| `get_athlete_profile` | Athlete name, email, and preferences |
| `get_athlete` | Sport settings including FTP, LTHR, max HR, and pace zones |
| `list_activities` | Activities within a date range |
| `get_activity` | Detailed metrics for a single activity (optionally with lap data) |
| `search_activities` | Search by name or tag (use `#tag` for exact tag match) |
| `get_athlete_summary` | Aggregate stats (count, time, distance, calories, load) for a date range |
| `list_wellness` | Wellness records within a date range |
| `get_wellness` | Single-day wellness record |
| `list_routes` | All saved routes |
| `get_route` | Route details, optionally with GPS lat/lng path |
| `list_events` | Planned calendar events within a date range (filterable by category) |
| `get_event` | Detailed info for a single planned event |
| `create_event` | Add a planned event to the calendar |
| `update_event` | Modify an existing calendar event |
| `list_event_tags` | All event tags used by the athlete |

## Prerequisites

- Node.js 18+
- An [Intervals.icu](https://intervals.icu) account
- An Intervals.icu API key (found in **Settings → API**)

## Setup

**1. Clone and install dependencies**

```bash
git clone <repo-url>
cd IntervalsMCP
npm install
```

**2. Configure environment variables**

```bash
cp .env.example .env
```

Edit `.env`:

```env
INTERVALS_API_KEY=your_api_key_from_intervals_icu_settings
INTERVALS_ATHLETE_ID=i0
```

> `INTERVALS_ATHLETE_ID` defaults to `i0` which resolves to your own athlete ID.

**3. Build**

```bash
npm run build
```

## Connecting to Claude

Add this server to your Claude Desktop (or any MCP-compatible client) configuration:

```json
{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/absolute/path/to/IntervalsMCP/dist/index.js"]
    }
  }
}
```

Claude Desktop config is typically located at:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## Development

```bash
# Watch mode — recompiles on file changes
npm run dev

# Run the compiled server directly
npm start
```

## Project Structure

```
src/
  index.ts            # MCP server entry point
  intervals-client.ts # Intervals.icu API HTTP client
  tools.ts            # MCP tool definitions
```