Intervals.icu MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Intervals.icu MCP Server Summarize my activity and wellness data for the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Intervals.icu MCP Server
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 | sh2. Clone and Setup Project
git clone <repository-url>
cd intervals-mcp
uv sync3. 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-28Get 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 2025Get Wellness Data
Show my wellness data from 2025-07-01 to 2025-07-28Get Grouped Wellness Data (Recommended for large datasets)
Show my weekly wellness summary for July 2025
Get my monthly wellness trends grouped by weekAvailable 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.pyProject 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 authenticationAPI Documentation
For more information about the intervals.icu API, visit:
License
This project is open source and available under the MIT License.
Available Tools
4 toolsget_activitiesA
Primary tool for fetching activities from intervals.icu for the configured athlete.
Best for: Getting complete list of activities within a date range, analyzing training history, exporting activity data. Not recommended for: Large date ranges without pagination; real-time activity tracking. Common mistakes: Using wrong date format (must be YYYY-MM-DD); requesting too large date ranges that may timeout. Prompt Example: "Get my activities from 2024-01-01 to 2024-01-31" or "Show me all activities from last week" Usage Example:
{
"name": "get_activities",
"arguments": {
"oldest_date": "2024-01-01",
"newest_date": "2024-01-31"
}
}Tool Relationships: Use this first to get activity list, then use get_grouped_activities for aggregated analysis, or get specific activity details as needed. Returns: Complete activity data including id, name, type, distance, duration, power, heart rate, and other metrics.
Parameters
oldest_date : str The oldest date to fetch activities from (format: YYYY-MM-DD). This parameter is required. newest_date : str, optional The newest date to fetch activities from (format: YYYY-MM-DD). If not provided, no upper date limit is applied.
Returns
dict Dictionary containing: - status: "success" or "error" - count: Number of activities returned - activities: List of transformed activity objects
Raises
ValidationError: If date format is invalid. IntervalsError: If the API request fails.
Inputs: oldest_date (required), newest_date. Returns: object
get_grouped_activitiesA
Tool for fetching and grouping activities to reduce data volume and show patterns.
Best for: Analyzing training patterns, summarizing activity by sport/time period, creating training reports, reducing data volume for large date ranges. Not recommended for: Getting individual activity details; real-time tracking. Common mistakes: Using invalid group_by value; requesting details for large datasets. Prompt Example: "Group my activities by sport from January" or "Show me weekly activity summary for last month" Usage Example:
{
"name": "get_grouped_activities",
"arguments": {
"oldest_date": "2024-01-01",
"newest_date": "2024-01-31",
"group_by": "week",
"include_details": false
}
}Tool Relationships: Use after get_activities to analyze patterns, or directly for summarized data when individual activities aren't needed. Returns: Grouped activity data with summaries (count, duration, distance) per group.
Parameters
oldest_date : str The oldest date to fetch activities from (format: YYYY-MM-DD). This parameter is required. newest_date : str, optional The newest date to fetch activities from (format: YYYY-MM-DD). If not provided, no upper date limit is applied. group_by : str, optional How to group activities. Options: "sport", "day", "week", "month". Default: "sport" include_details : bool, optional Whether to include filtered activity details in each group. Default: False
Returns
dict Dictionary containing: - groups: Dictionary of groups with summaries - total_activities: Total number of activities - Additional metadata based on grouping type
Raises
ValidationError: If parameters are invalid. IntervalsError: If the API request fails.
Inputs: oldest_date (required), newest_date, group_by, include_details. Returns: object
get_grouped_wellnessA
Tool for fetching and grouping wellness data to show trends and patterns.
Best for: Analyzing wellness trends over time, creating health reports, tracking recovery patterns, monitoring training stress balance, identifying correlations. Not recommended for: Individual day analysis; real-time monitoring. Common mistakes: Using invalid group_by value; requesting details for very large datasets. Prompt Example: "Show me monthly wellness trends for 2024" or "Group my wellness data by week for the last 3 months" Usage Example:
{
"name": "get_grouped_wellness",
"arguments": {
"oldest_date": "2024-01-01",
"newest_date": "2024-03-31",
"group_by": "month",
"include_details": false
}
}Tool Relationships: Use after get_wellness to analyze patterns, or directly for trend analysis when individual records aren't needed. Returns: Grouped wellness data with averages and statistics per time period.
Parameters
oldest_date : str The oldest date to fetch wellness data from (format: YYYY-MM-DD). This parameter is required. newest_date : str, optional The newest date to fetch wellness data from (format: YYYY-MM-DD). If not provided, no upper date limit is applied. group_by : str, optional How to group wellness data. Options: "week", "month", "all". Default: "month" include_details : bool, optional Whether to include individual records in each group. Default: False
Returns
dict Dictionary containing: - status: "success" or "error" - groups: Dictionary of groups with summaries (when not "all") - summary: Aggregate statistics (when group_by is "all") - total_records: Total number of wellness records - Additional metadata based on grouping type
Raises
ValidationError: If parameters are invalid. IntervalsError: If the API request fails.
Inputs: oldest_date (required), newest_date, group_by, include_details. Returns: object
get_wellnessA
Primary tool for fetching wellness data from intervals.icu for the configured athlete.
Best for: Getting daily wellness metrics, tracking health trends, monitoring recovery, analyzing sleep patterns, weight tracking. Not recommended for: Real-time monitoring; medical diagnosis; very large date ranges. Common mistakes: Using wrong date format (must be YYYY-MM-DD); requesting years of data at once. Prompt Example: "Get my wellness data from 2024-01-01 to 2024-01-31" or "Show me wellness metrics for last month" Usage Example:
{
"name": "get_wellness",
"arguments": {
"oldest_date": "2024-01-01",
"newest_date": "2024-01-31"
}
}Tool Relationships: Use this first to get wellness records, then use get_grouped_wellness for trend analysis or summary statistics. Returns: Complete wellness data including weight, HRV, resting HR, sleep, fatigue, mood, motivation, and training metrics (ATL/CTL/TSB).
Parameters
oldest_date : str The oldest date to fetch wellness data from (format: YYYY-MM-DD). This parameter is required. newest_date : str, optional The newest date to fetch wellness data from (format: YYYY-MM-DD). If not provided, no upper date limit is applied.
Returns
dict Dictionary containing: - status: "success" or "error" - count: Number of wellness records returned - wellness: List of transformed wellness objects - date_range: Date range of the wellness data
Raises
ValidationError: If date format is invalid. IntervalsError: If the API request fails.
Inputs: oldest_date (required), newest_date. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: get_activities retrieves individual activity records, get_grouped_activities provides aggregated activity summaries, get_wellness fetches individual wellness metrics, and get_grouped_wellness offers aggregated wellness trends. The descriptions explicitly differentiate between individual data retrieval and grouped analysis for both domains.
All tools follow a perfectly consistent verb_noun pattern with clear prefixes: get_activities, get_grouped_activities, get_wellness, get_grouped_wellness. The naming convention is uniform throughout, using snake_case consistently and maintaining parallel structure between activity and wellness domains.
Four tools is reasonable for a fitness/wellness data server, covering the core domains of activities and wellness with both individual and grouped variants. However, the count feels slightly minimal - there might be room for additional operations like creating or updating records, though the current set adequately serves basic retrieval and analysis needs.
The toolset provides excellent read/analysis coverage for activities and wellness data, but lacks any write operations (create, update, delete). For a fitness tracking platform where users might want to log new activities or update wellness metrics, this represents a notable gap. The surface is complete for retrieval and analysis but incomplete for full CRUD lifecycle management.
Maintenance
Related MCP Connectors
Connect Intervals.icu to Claude and ChatGPT: read training, plan workouts. Training never stored.
Ask your AI about your fitness: activities and data from Garmin, COROS, Strava, GPX and more
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI assistants to access and analyze intervals.icu training data including activities, fitness metrics (CTL/ATL/TSB), wellness stats, and calendar events. Supports natural language querying of athletic performance for training insights and workout planning.6-
- AlicenseAqualityDmaintenanceEnables interaction with Intervals.icu data, including activities, wellness, and calendar events, via natural language.1025 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude AI to access and manage intervals.icu training data, including workouts, wellness, and fitness trends, through natural language conversation.MIT
- AlicenseAqualityDmaintenanceEnables Claude and ChatGPT to retrieve and manage activities, intervals, events, wellness data, power curves, and custom items through the Intervals.icu API.21GPL 3.0