mrgeorgegray/intervals-icu-mcp

Intervals.icu MCP Server

A Model Context Protocol (MCP) server that provides access to the Intervals.icu API. Interact with your training data, activities, events, and wellness information.

Intervals.icu is a powerful training platform for cyclists, runners, and other athletes that provides detailed analytics, workout planning, and performance tracking.

Inspiration

This project was inspired by the excellent Python-based intervals-mcp-server by @mvilanova and the community discussion on the Intervals.icu forum. I decided to rewrite it in TypeScript and add different tools to provide an alternative implementation.

Alternative: ChatGPT Connector

If you prefer not to use MCP, there's also a ChatGPT connector for Intervals.icu available that provides similar functionality through ChatGPT's GPTs feature.

Features

• Activity Management: Retrieve and analyze your training activities
• Event Creation: Schedule workouts, races, and other events
• Athlete Profile: Access your athlete details and statistics
• Wellness Data: Get insights into your health and recovery metrics
• Bulk Operations: Create and delete multiple events efficiently

Requirements

• Node.js 22.x or higher
• Claude Desktop with MCP support
• Intervals.icu Account with API access
• API Key from Intervals.icu

Setup

1. Install the Package

Clone the repository:

git clone git@github.com:mrgeorgegray/intervals-icu-mcp
cd intervals-icu-mcp
npm install

2. Build the Project

npm run build

3. Environment Configuration

If you use this with the inspector copy the example environment file and update it with your credentials, else we'll just add env vars to the Claude config later:

cp .env.example .env

Then edit the .env file with your actual values:

INTERVALS_API_KEY=your_api_key_here
INTERVALS_ATHLETE_ID=your_athlete_id_here
DEBUG=false

Getting your API credentials:

You get an API key from your intervals settings page (look for "Developer Settings" near the bottom), or follow details here.

4. Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration along with the correct paths and env vars:

NOTE: make sure you use the full path to your node version in the command key, to get this please run:

which node

{
  "mcpServers": {
    "intervals-icu-mcp": {
      "command": "/path/to/your/node",
      "args": ["/path/to/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "your_api_key_here",
        "INTERVALS_ATHLETE_ID": "your_athlete_id_here"
      }
    }
  }
}

Using with Claude

Once configured, Claude can access the following tools:

Activity Tools

• getActivities - Retrieve a list of your training activities

  • Filter by date range, limit results, include/exclude unnamed activities
  • Returns formatted activity summaries with key metrics

• getActivityDetails - Get detailed information about a specific activity

  • Provides comprehensive data including power, heart rate, GPS data
  • Useful for analyzing performance and training effectiveness

Event Management

• createEvent - Schedule a new training event or workout

  • Supports all Intervals.icu activity types (Ride, Run, Swim, etc.)
  • Configure event categories, descriptions, and scheduling

• createBulkEvents - Create multiple events at once

  • Efficient for setting up training blocks or recurring workouts

• deleteEvent - Remove a specific event from your calendar

• deleteBulkEvents - Remove multiple events efficiently

Profile and Wellness

• getAthleteDetails - Access your athlete profile information

  • View statistics, achievements, and account details

• getWellnessData - Retrieve health and recovery metrics

  • Includes sleep, stress, fatigue, and other wellness indicators

Event Information

• getEvents - List scheduled events and workouts

  • Filter by date range and event types

• getEventDetails - Get detailed information about a specific event

Development

Available Commands

# Build the project
npm run build

# Start the server in development mode
npm run dev

# Run the MCP inspector for debugging
npm run inspector

# Generate TypeScript client from OpenAPI spec
npm run generate-client

# Linting and formatting
npm run lint
npm run lint:fix
npm run prettier:fix

Project Structure

src/
├── client/          # Generated API client
├── tools/           # MCP tool implementations
├── utils/           # Utility functions
└── index.ts         # Main server entry point

API Client Generation

The project uses @hey-api/openapi-ts to generate a TypeScript client from the Intervals.icu OpenAPI specification:

npm run generate-client

This generates the client in src/client/generated/ based on the openapi-spec.json file. The entire API is currently available, but only certain tools have been added so far.

Debugging

Enable debug mode by setting DEBUG=true in your environment variables. This will provide detailed logging of server operations.

Use the MCP Inspector for testing and debugging:

npm run inspector

Troubleshooting

Common Issues

1. "INTERVALS_ATHLETE_ID environment variable is not set"

   • Ensure your .env file contains the correct athlete ID
   • Verify the athlete ID in your Intervals.icu profile

2. API authentication errors

   • Check that your API key is valid and has the necessary permissions
   • Ensure the API key is correctly set in your environment variables

3. Build errors

   • Make sure you're using Node.js 22.x or higher
   • Run npm install to ensure all dependencies are installed

License

This project is licensed under the GNU General Public License v3.0.