Intervals.icu MCP Server

Model Context Protocol (MCP) server for connecting Claude with the Intervals.icu API. It provides tools for authentication and data retrieval for activities, events, and wellness data.

Requirements

• Python 3.10 or higher
• Model Context Protocol (MCP) Python SDK
• httpx
• python-dotenv

Setup

1. Install uv (recommended)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone this repository

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. Create and activate a virtual environment

# Create virtual environment
uv venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. Install dependencies

uv pip install -e .

5. Set up environment variables

Make a copy of .env.example and name it .env by running the following command:

cp .env.example .env

Then edit the .env file and set your Intervals.icu athlete id and API key:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Getting your Intervals.icu API Key

1. Log in to your Intervals.icu account
2. Go to Settings > API
3. Generate a new API key

Finding your Athlete ID

Your athlete ID is typically visible in the URL when you're logged into Intervals.icu. It looks like:

• https://intervals.icu/athlete/i12345/... where i12345 is your athlete ID

Usage

1. Configure Claude Desktop

To use this server with Claude Desktop, you need to add it to your Claude Desktop configuration.

1. Run the following from the intervals_mcp_server directory to configure Claude Desktop:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu MCP Server"

2. If you open your Claude Desktop App configuration file claude_desktop_config.json, it should look like this:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ]
    }
  }
}

Where /path/to/ is the path to the intervals-mcp-server code folder in your system.

3. Restart Claude Desktop.

2. Use the MCP server with Claude

Once the server is running and Claude Desktop is configured, you can use the following tools to ask questions about your past and future activities, events, and wellness data.

• get_activities: Retrieve a list of activities
• get_activity_details: Get detailed information for a specific activity
• get_activity_intervals: Get detailed interval data for a specific activity
• get_wellness_data: Fetch wellness data
• get_events: Retrieve upcoming events (workouts, races, etc.)
• get_event_by_id: Get detailed information for a specific event

License

The GNU General Public License v3.0