Mvilanova Intervals MCP Server

🚀 Intervals.icu MCP Server

This MCP (Model Context Protocol) server is used to connect Claude with the Intervals.icu API. It provides tools for authentication and retrieval of activity, event, and health data.

🚀 Quick Start

This MCP server serves as a bridge between Claude and the Intervals.icu API, offering authentication and data retrieval capabilities for activities, events, and health information.

✨ Features

• Connects Claude with the Intervals.icu API.
• Provides authentication tools.
• Enables retrieval of activity, event, and health data.

📦 Installation

Requirements

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

Steps

1. Install uv (Recommended)

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

2. Clone this repository

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

3. Create and activate a virtual environment

# Create a virtual environment
uv venv

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

4. Install dependencies

uv pip install -e .

5. Set environment variables

Copy .env.example and rename it to .env:

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

Obtain your Intervals.icu API key

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

Find your athlete ID

Your athlete ID is usually displayed in the URL when you log in to Intervals.icu, in the following format:

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

💻 Usage Examples

Basic Usage

1. Configure Claude Desktop

To use this server with Claude Desktop, add it to the Claude Desktop configuration.

1. Run the following command in 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 application 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 on 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 query past and future activities, events, and health data.

• get_activities: Retrieve a list of activities.
• get_activity_details: Get detailed information about a specific activity.
• get_activity_intervals: Get detailed interval data for a specific activity.
• get_wellness_data: Extract health data.
• get_events: Retrieve upcoming events (training, competitions, etc.).
• get_event_by_id: Get detailed information about a specific event.

📄 License

GNU General Public License v3.0