# Intervals.icu Running Analysis MCP Server

An MCP (Model Context Protocol) Server for analyzing running data from [Intervals.icu](https://intervals.icu), specifically designed for integration with **Claude Desktop**.

---

## 🚀 Features & MCP Tools

This MCP server provides 5 dedicated tools for comprehensive running data analysis:

| Tool Name | Description |
| --- | --- |
| `get_athlete_profile` | Retrieves athlete profile, Heart Rate (HR) zones, Pace zones, and threshold metrics (LTHR / Threshold Pace). |
| `list_running_activities` | Fetches recent running activities with distance, pace, HR, cadence, training load, and intensity. |
| `get_activity_detail` | Detailed breakdown of a single running session (per-km lap splits, GAP pace, HR zones, cadence, elevation). |
| `get_running_fitness_wellness` | Tracks fitness metrics (Fitness/CTL, Fatigue/ATL, Form/TSB, Resting HR, HRV, Sleep). |
| `get_running_summary` | Aggregates weekly/monthly running volume and trends (total distance, duration, average pace, training load breakdown). |

---

## 🗝️ Prerequisites & Intervals.icu Credentials

1. Log into your [Intervals.icu Settings](https://intervals.icu/settings).
2. Scroll down to the **API Access** section.
3. Copy your **API Key**.
4. Obtain your **Athlete ID** (found in your profile URL `intervals.icu/athletes/iXXXXX` or use `"current"`).

---

## 🛠️ Installation & Build

### 1. Install Dependencies & Build
Open a terminal in the project directory:

```bash
npm install
npm run build
```

### 2. Verification / Self-check
Run the runnable test script to verify formatting helpers:

```bash
npm run check
```

---

## ⚙️ Claude Desktop Configuration

Add the server configuration to your **`claude_desktop_config.json`** file.

> **Claude Desktop Config File Location (Windows):**  
> `%APPDATA%\Claude\claude_desktop_config.json`  
> *(e.g., `C:\Users\<Username>\AppData\Roaming\Claude\claude_desktop_config.json`)*

```json
{
  "mcpServers": {
    "intervals-running": {
      "command": "node",
      "args": [
        "d:/Work/Personal/intervals-mcp/dist/index.js"
      ],
      "env": {
        "INTERVALS_API_KEY": "YOUR_INTERVALS_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "current"
      }
    }
  }
}
```

> ⚠️ *Note:* Replace `YOUR_INTERVALS_API_KEY_HERE` with your actual API key from Intervals.icu, and update `INTERVALS_ATHLETE_ID` if needed.

---

## 💬 Example Prompts in Claude Desktop

Once configured, restart Claude Desktop and try asking:

- *"Analyze my latest running session from Intervals.icu and give me actionable feedback."*
- *"How are my Fitness (CTL), Fatigue (ATL), and Form (TSB) trending over the last 30 days?"*
- *"Give me a weekly summary of my running volume and average pace for this month."*
- *"Break down the splits, cadence, and heart rate zones for my most recent long run."*

---

## 📄 License

ISC