Intervals.icu

You run a Model Context Protocol (MCP) server that connects Claude and ChatGPT to the Intervals.icu API. It provides authentication and data retrieval for activities, events, and wellness data, enabling intelligent assistants to access your intervals data securely and on demand.

How to use

Set up an MCP client to communicate with the Intervals.icu MCP server. You can access your activities, events, and wellness data through clearly defined functions that fetch lists, details, and intervals, then pass that data to your chat assistants. Use the server to answer questions about past workouts, upcoming events, and wellness trends. When using Claude or ChatGPT, you can query the server for specific endpoints like the list of activities, details for a single activity, interval data for an activity, wellness data, upcoming events, and individual event details.

How to install

Prerequisites: Python 3.12 or higher, the MCP Python SDK, httpx, and python-dotenv. You will also use the uv helper for managing Python environments and dependencies.

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

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

# Create virtual environment with Python 3.12
uv venv --python 3.12

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

uv sync

cp .env.example .env

Then edit the .env file to set your Intervals.icu credentials:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

To run the MCP server locally and expose it for clients, use the Python runner with the server module path as shown here. This starts the server in a local Python process ready for MCP clients to connect via stdio transport.

python src/intervals_mcp_server/server.py

Additional setup notes

If you plan to use Claude Desktop or ChatGPT with an SSE-based MCP endpoint, start the server in SSE mode and expose it to the outside world if needed. You can run the server with environment variables that configure the SSE transport and API base URL, then connect your MCP client to the provided SSE URL.

export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
python src/intervals_mcp_server/server.py

The server will print the full SSE URL, such as http://127.0.0.1:8765/sse, which you can forward with a tunnel if you need a public address for ChatGPT or Claude to reach it.

## Troubleshooting and maintenance

If you encounter issues when starting Claude Desktop after making configuration changes, remove the existing MCP entry in claude\_desktop\_config.json and reconfigure using the standard install command.

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

## Development and testing

Develop and test using the project’s dependencies and test suite. Install development dependencies and run tests to verify functionality during changes.

uv sync --all-extras pytest -v tests

## Running the server for development

During development you can run the MCP server directly to iterate quickly with debugging output.

mcp run src/intervals_mcp_server/server.py

## Available tools

### get\_activities

Retrieve a list of activities from Intervals.icu, including basic metadata such as IDs, names, and dates.

### get\_activity\_details

Fetch detailed information for a specific activity, including stats and metadata.

### get\_activity\_intervals

Retrieve detailed interval data for a specific activity to analyze pace, splits, and timing.

### get\_wellness\_data

Fetch wellness data such as sleep, stress, or other wellness metrics available from Intervals.icu.

### get\_events

Retrieve upcoming events such as workouts or races.

### get\_event\_by\_id

Get detailed information for a specific event by its identifier.