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)
curl -LsSf https://astral.sh/uv/install.sh | sh
2. Clone and Setup Project
git clone <repository-url>
cd intervals-mcp
uv sync
3. Get Your Intervals.icu Credentials
- Go to intervals.icu/settings
- Scroll down to "Developer Settings"
- Generate an API key
- Note your athlete ID (e.g.,
i335136from 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)
{
"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-mcpwith the absolute path to this repositoryyour-api-key-herewith your intervals.icu API keyyour-athlete-idwith 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 formatnewest_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 formatnewest_date(optional): End date in YYYY-MM-DD formatgroup_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 formatnewest_date(optional): End date in YYYY-MM-DD format
Development
Testing the Server
# 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:
License
This project is open source and available under the MIT License.