# Intervals.icu MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with intervals.icu fitness tracking data.
## Features
- Fetch activities data with date filtering
- Retrieve wellness metrics with date filtering
- Clean data output (removes empty/null values)
- Basic authentication with intervals.icu API
## Requirements
- Python 3.12+
- UV package manager
- Intervals.icu API key
- Your intervals.icu athlete ID
## Installation
### 1. Install UV (if not already installed)
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 2. Clone and Setup Project
```bash
git clone <repository-url>
cd intervals-mcp
uv sync
```
### 3. Get Your Intervals.icu Credentials
1. Go to [intervals.icu/settings](https://intervals.icu/settings)
2. Scroll down to "Developer Settings"
3. Generate an API key
4. Note your athlete ID (e.g., `i335136` from your profile URL)
### 4. Configure Claude Desktop
Add the following to your Claude Desktop configuration file:
**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
```json
{
"mcpServers": {
"intervals-icu": {
"command": "uv",
"args": [
"--directory",
"/path/to/intervals-mcp",
"run",
"main.py"
],
"env": {
"INTERVALS_API_KEY": "your-api-key-here",
"INTERVALS_ATHLETE_ID": "your-athlete-id"
}
}
}
}
```
Replace:
- `/path/to/intervals-mcp` with the absolute path to this repository
- `your-api-key-here` with your intervals.icu API key
- `your-athlete-id` with your athlete ID (e.g., `i335136`)
### 5. Restart Claude Desktop
Restart Claude Desktop to load the new MCP server.
## Usage
Once configured, you can use these tools in Claude Desktop:
### Get Activities
```
Get my activities from 2025-07-28
```
### Get Grouped Activities (Recommended for large datasets)
```
Get my activities grouped by sport from 2025-07-01 to 2025-07-28
Show my weekly activity summary for July 2025
```
### Get Wellness Data
```
Show my wellness data from 2025-07-01 to 2025-07-28
```
### Get Grouped Wellness Data (Recommended for large datasets)
```
Show my weekly wellness summary for July 2025
Get my monthly wellness trends grouped by week
```
## Available Tools
### `get_activities(oldest_date, newest_date=None)`
Fetches detailed activities from intervals.icu. Use for small datasets or when you need full activity details.
**Parameters:**
- `oldest_date` (required): Start date in YYYY-MM-DD format
- `newest_date` (optional): End date in YYYY-MM-DD format
### `get_grouped_activities(oldest_date, newest_date=None, group_by="sport", include_details=False)`
Fetches and groups activities to reduce data volume. **Recommended for analyzing multiple activities or time periods.**
**Parameters:**
- `oldest_date` (required): Start date in YYYY-MM-DD format
- `newest_date` (optional): End date in YYYY-MM-DD format
- `group_by` (optional): Grouping method - "sport", "day", "week", or "month" (default: "sport")
- `include_details` (optional): Include filtered activity details in each group (default: false)
**Returns grouped statistics:** activity counts, total time/distance/calories, averages per group, and overall totals.
### `get_wellness(oldest_date, newest_date=None)`
Fetches wellness metrics from intervals.icu.
**Parameters:**
- `oldest_date` (required): Start date in YYYY-MM-DD format
- `newest_date` (optional): End date in YYYY-MM-DD format
## Development
### Testing the Server
```bash
# Test imports and basic structure
INTERVALS_API_KEY=test_key INTERVALS_ATHLETE_ID=i335136 uv run python -c "import tools.activities; import tools.wellness; print('OK')"
# Run the server locally
INTERVALS_API_KEY=your_key INTERVALS_ATHLETE_ID=your_id uv run main.py
```
### Project Structure
```
intervals-mcp/
├── pyproject.toml # UV project configuration
├── main.py # Entry point
├── server.py # FastMCP server instance
├── tools/
│ ├── activities.py # Activities data tool
│ └── wellness.py # Wellness data tool
└── utils/
└── intervals_client.py # HTTP client with authentication
```
## API Documentation
For more information about the intervals.icu API, visit:
- [API Documentation](https://intervals.icu/api-docs.html)
- [Community Forum](https://forum.intervals.icu/t/api-access-to-intervals-icu/609)
## License
This project is open source and available under the MIT License.
