XERT Cycling Training

A Model Context Protocol (MCP) server that connects Claude to the XERT API, providing access to your fitness signature, training load, workouts, and activities.

Features

• 📊 Fitness Signature - Get your current FTP, LTP, HIE, and Peak Power
• 🎯 Training Status - Check freshness, training load, and recommended XSS
• 🏋️ Workout of the Day - AI-powered workout recommendations
• 📋 Workouts - List, view details, and export (ZWO/ERG)
• 🚴 Activities - Browse activities with full XSS metrics and MPA data
• ⬆️ Upload - Upload FIT files for analysis

Installation

Prerequisites

• Node.js 18 or later
• A XERT account (free or premium)

Setup

1. Clone the repository:

   git clone https://github.com/Milofax/xert-mcp.git
   cd xert-mcp
   

2. Install dependencies:

   npm install
   

3. Authenticate with XERT:

   npm run setup-auth
   

   Enter your XERT email and password when prompted. Tokens will be saved to .env.

4. Build the project:

   npm run build
   

Configuration

Add to your Claude Desktop config:

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

{
  "mcpServers": {
    "xert": {
      "command": "node",
      "args": ["/path/to/xert-mcp/dist/server.js"]
    }
  }
}

Replace /path/to/xert-mcp with the actual path to your installation.

Restart Claude Desktop to load the server.

Docker

You can also run the server via Docker:

1. Build the image

docker build -t xert-mcp .

2. Get your XERT tokens

Run the setup script locally first to authenticate:

npm install
npm run setup-auth

This creates xert-tokens.json with your access and refresh tokens.

3. Configure Claude Desktop

{
  "mcpServers": {
    "xert": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "XERT_ACCESS_TOKEN",
        "-e", "XERT_REFRESH_TOKEN",
        "xert-mcp"
      ],
      "env": {
        "XERT_ACCESS_TOKEN": "your-access-token-from-xert-tokens.json",
        "XERT_REFRESH_TOKEN": "your-refresh-token-from-xert-tokens.json"
      }
    }
  }
}

Note: Access tokens expire after 7 days. When they expire, run npm run setup-auth again and update the tokens in your config.

Available Tools

Tool	Description
xert-get-training-info	Get fitness signature, training status, load, and WOTD
xert-list-workouts	List all your saved workouts
xert-get-workout	Get detailed workout intervals
xert-download-workout	Export workout as ZWO or ERG file
xert-list-activities	List activities in a time range
xert-get-activity	Get activity details with XSS metrics
xert-upload-fit	Upload a FIT file for analysis

Usage Examples

Ask Claude questions like:

• "What's my current FTP and training status?"
• "Show me my workout of the day"
• "List my activities from the last 7 days"
• "What was my XSS breakdown for yesterday's ride?"
• "Did I have any breakthroughs this week?"
• "Show me my saved workouts"
• "Export my 'Sunday Endurance' workout as a ZWO file"

XERT Concepts

• FTP - Functional Threshold Power (1-hour sustainable power)
• LTP - Lower Threshold Power (fat-burning threshold)
• HIE - High Intensity Energy (anaerobic work capacity)
• PP - Peak Power (maximum instantaneous power)
• XSS - Xert Strain Score (training load metric)
• MPA - Maximum Power Available (real-time power limit)

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

Token Management

The server handles tokens automatically:

• Access tokens expire after 7 days
• Refresh tokens expire after 6 months
• Tokens are stored in xert-tokens.json (created automatically)
• On 401 errors, tokens are refreshed automatically
• New tokens are persisted to survive server restarts

If authentication fails completely, run npm run setup-auth again.

MCP Funnel / Environment Variables

When using mcp-funnel or similar tools, tokens from xert-tokens.json take priority over environment variables. This ensures refreshed tokens are used even when env vars contain outdated values.

License

MIT

Credits

• XERT - Advanced cycling analytics
• Model Context Protocol - AI integration standard