Intervals.icu MCP Server (TypeScript)

Model Context Protocol (MCP) server for connecting Claude and ChatGPT with the Intervals.icu API. It provides tools for authentication and data retrieval for activities, events, and wellness data.

This is the TypeScript/Node.js implementation, inspired by the Python version.

Requirements

• Node.js 18.0.0 or higher
• npm or yarn

Setup

1. Clone this repository

git clone <your-repo-url>
cd intervals-mcp-node

2. Install dependencies

npm install

3. Set up environment variables

Make a copy of .env.example and name it .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

Getting your Intervals.icu API Key

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

Finding your Athlete ID

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

4. Build the project

npm run build

Development

To run the server in development mode with auto-reload:

npm run dev

To run the built server:

npm start

Usage with Claude Desktop

1. Configure Claude Desktop

Add this server to your Claude Desktop configuration file (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "node",
      "args": [
        "/absolute/path/to/intervals-mcp-node/dist/index.js"
      ],
      "env": {
        "API_KEY": "your_api_key_here",
        "ATHLETE_ID": "your_athlete_id_here",
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1"
      }
    }
  }
}

Replace /absolute/path/to/intervals-mcp-node with the actual path to this project directory.

2. Restart Claude Desktop

After updating the configuration, restart Claude Desktop. You should see the Intervals.icu tools available in Claude.

Available Tools

The server provides the following MCP tools:

• get_activities - Retrieve activities for a date range
• get_activity_details - Get detailed information about a specific activity
• get_activity_intervals - Get intervals for an activity
• get_activity_streams - Get time series data (power, heart rate, etc.) for an activity
• get_events - Retrieve events (workouts, races) for a date range
• get_event_by_id - Get a specific event by ID
• add_event - Add a new event to the calendar
• delete_event - Delete an event from the calendar
• get_wellness_data - Get wellness data (fitness, fatigue, sleep, etc.)

Project Structure

intervals-mcp-node/
├── src/
│   ├── api/
│   │   └── client.ts          # API client for Intervals.icu
│   ├── tools/
│   │   ├── activities.ts      # Activity-related tools
│   │   ├── events.ts          # Event-related tools
│   │   └── wellness.ts        # Wellness-related tools
│   ├── utils/
│   │   ├── formatting.ts      # Formatting utilities
│   │   └── validation.ts      # Validation utilities
│   ├── config.ts              # Configuration management
│   ├── types.ts               # TypeScript type definitions
│   └── index.ts               # Main server entry point
├── dist/                      # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Development Guidelines

• TypeScript: All source code is written in TypeScript with strict type checking
• Linting: Use npm run lint to check code style
• Testing: Run tests with npm test (tests to be implemented)

Troubleshooting

Server fails to start

1. Ensure all dependencies are installed: npm install
2. Build the project: npm run build
3. Check that your .env file contains valid credentials

Claude Desktop doesn't see the server

1. Verify the path in claude_desktop_config.json is absolute and correct
2. Ensure the built dist/index.js file exists
3. Restart Claude Desktop completely

API authentication errors

1. Verify your API key is correct in the .env file
2. Check that your athlete ID matches your Intervals.icu account
3. Ensure your API key hasn't expired

License

GPL-3.0-only

Author

Vincent Racelle

Credits

This project is inspired by and based on the Python implementation by Marc Vilanova.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.