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.

If you find the Model Context Protocol (MCP) server useful, please consider supporting its continued development with a donation.

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

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
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

uv sync

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

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

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

This project is actively developed, with new features and fixes added regularly. To stay up to date, follow these steps:

⚠️ Make sure you don’t have uncommitted changes before running this command.

git checkout main && git pull

Activate your virtual environment and sync dependencies:

source .venv/bin/activate
uv sync

If Claude Desktop fails due to configuration changes, follow these steps:

1. Delete the existing entry in claude_desktop_config.json.
2. Reconfigure Claude Desktop from the intervals_mcp_server directory:

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

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" --with-editable . --env-file .env

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

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/Users/<USERNAME>/.cargo/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/intervals-mcp-server",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

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

If you observe the following error messages when you open Claude Desktop, include the full path to uv in the command key in the claude_desktop_config.json configuration file. You can get the full path by running which uv in the terminal.

2025-04-28T10:21:11.462Z [info] [Intervals.icu MCP Server] Initializing server...
2025-04-28T10:21:11.477Z [error] [Intervals.icu MCP Server] spawn uv ENOENT
2025-04-28T10:21:11.477Z [error] [Intervals.icu MCP Server] spawn uv ENOENT
2025-04-28T10:21:11.481Z [info] [Intervals.icu MCP Server] Server transport closed
2025-04-28T10:21:11.481Z [info] [Intervals.icu MCP Server] Client transport closed

3. Restart Claude Desktop.

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

Install development dependencies and run the test suite with:

uv sync --all-extras
pytest -v tests

To start the server manually (useful when developing or testing), run:

mcp run src/intervals_mcp_server/server.py

The GNU General Public License v3.0