Intervals.icu MCP Server

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

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.