Skip to main content
Glama
Intervals.icu MCP Server

Intervals.icu MCP Server

by VSidhArt

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 | sh

2. Clone and Setup Project

git clone <repository-url>
cd intervals-mcp
uv sync

3. Get Your Intervals.icu Credentials

  1. Go to 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)

{
  "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 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
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

# 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.

Available Tools

4 tools
get_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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers